Share tokenized payment details securely with PCI-compliant third-party providers

Forward Payment Details

Forward Payment Details allows you to securely share stored payment credentials with PCI-compliant third parties. This enables use cases like multi-processor routing, fraud prevention services, and specialized payment providers without exposing raw card data.

Overview

When you forward payment details, Plexy securely transmits the underlying card data to an authorized third-party endpoint. The third party must be PCI DSS compliant and registered with Plexy.

Use Cases

Multi-Processor Routing

Route transactions to different payment processors based on business rules while using a single token. For high-value transactions, forward the token to a premium processor using POST https://api.plexypay.com/v2/tokens/{token_id}/forward. For standard transactions, process normally via POST https://api.plexypay.com/v2/payments.

Fraud Prevention Services

Send card details to specialized fraud detection services before processing.

curl -X POST https://api.plexypay.com/v2/tokens/tok_card_visa_4242/forward \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "destination_id": "dest_fraud_service",
    "fields": ["card_number", "expiry"],
    "include_metadata": true
  }'

If the fraud score is acceptable, proceed with the payment via POST https://api.plexypay.com/v2/payments.

Travel and Hospitality

Share payment details with hotels, airlines, or car rental companies for booking guarantees.

Marketplace Payments

Forward buyer payment details to seller payment processors in a marketplace model.

Prerequisites

Before using Forward Payment Details, you must:

Enable the feature - Contact Plexy support to enable forwarding on your account
Register destinations - Add PCI-compliant third parties in the Plexy Dashboard
Provide compliance documentation - Third parties must provide their PCI DSS Attestation of Compliance (AOC)

Forward Payment Details is only available to merchants with enhanced security configurations. Contact support@plexy.money to request access.

Register a Forwarding Destination

Before forwarding tokens, register the third-party endpoint in your Plexy account.

Go to Settings > Forwarding Destinations in the Plexy Dashboard.

Click Add Destination and provide: - Name: A friendly identifier (e.g., "Premium Processor") - Endpoint URL: The HTTPS endpoint that will receive card data - Authentication: API key or certificate details - PCI AOC: Upload the third party's Attestation of Compliance

Select which payment details to forward: - Card number (PAN) - Expiry date - Cardholder name - Billing address

Plexy will validate the endpoint and encryption before activation.

Forward Payment Details

Once a destination is registered, you can forward token data.

curl -X POST https://api.plexypay.com/v2/tokens/tok_card_visa_4242/forward \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "destination_id": "dest_premium_processor",
    "fields": ["card_number", "expiry", "cardholder_name"],
    "reference": "booking_12345",
    "metadata": {
      "booking_id": "BK-2026-12345",
      "guest_name": "John Smith"
    }
  }'

Response

{
  "id": "fwd_abc123xyz789",
  "token_id": "tok_card_visa_4242",
  "destination_id": "dest_premium_processor",
  "status": "completed",
  "fields_forwarded": ["card_number", "expiry", "cardholder_name"],
  "reference": "booking_12345",
  "destination_reference": "PROC-REF-98765",
  "destination_response": {
    "authorization_code": "AUTH123",
    "status": "approved"
  },
  "created_at": "2026-03-25T18:00:00Z"
}

Forward with Custom Payload

Some destinations require specific data formats. You can include a custom payload that Plexy will merge with the card data.

curl -X POST https://api.plexypay.com/v2/tokens/tok_card_visa_4242/forward \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "destination_id": "dest_hotel_booking",
    "fields": ["card_number", "expiry", "cardholder_name", "billing_address"],
    "custom_payload": {
      "reservation_id": "RES-2026-98765",
      "check_in": "2026-04-15",
      "check_out": "2026-04-18",
      "room_type": "deluxe",
      "amount": {
        "value": 45000,
        "currency": "USD"
      }
    }
  }'

List Forwarding History

Retrieve a history of forwarding operations for a token.

curl -X GET "https://api.plexypay.com/v2/tokens/tok_card_visa_4242/forwards" \
  -H "x-api-key: YOUR_API_KEY"

Response

{
  "data": [
    {
      "id": "fwd_abc123xyz789",
      "token_id": "tok_card_visa_4242",
      "destination_id": "dest_premium_processor",
      "status": "completed",
      "reference": "booking_12345",
      "created_at": "2026-03-25T18:00:00Z"
    },
    {
      "id": "fwd_def456uvw012",
      "token_id": "tok_card_visa_4242",
      "destination_id": "dest_fraud_service",
      "status": "completed",
      "reference": "check_67890",
      "created_at": "2026-03-24T12:30:00Z"
    }
  ],
  "has_more": false
}

Retrieve Forward Details

Get detailed information about a specific forwarding operation.

curl -X GET https://api.plexypay.com/v2/forwards/fwd_abc123xyz789 \
  -H "x-api-key: YOUR_API_KEY"

Request Parameters

Parameter	Type	Required	Description
`destination_id`	string	Yes	Registered destination identifier
`fields`	array	Yes	Fields to forward (see below)
`reference`	string	No	Your reference for this operation
`custom_payload`	object	No	Additional data to send to destination
`metadata`	object	No	Data stored with the forward record

Available Fields

Field	Description
`card_number`	Full card number (PAN)
`expiry`	Card expiration date
`cardholder_name`	Name on the card
`billing_address`	Full billing address
`cvc`	Card security code (if stored)

CVC is typically not stored for PCI compliance reasons. It can only be forwarded during the initial tokenization flow using a special session-based forward.

Security Requirements

For Merchants

API key security - Use server-side calls only; never expose forwarding in client code
Logging - Do not log forwarding requests or responses containing card data
Access control - Restrict forwarding API access to authorized personnel
Monitoring - Set up alerts for unusual forwarding patterns

For Destinations

Third-party destinations must meet these requirements:

Requirement	Description
PCI DSS Level 1	Must maintain active PCI DSS compliance
TLS 1.2+	HTTPS endpoint with TLS 1.2 or higher
IP Allowlisting	Must accept requests from Plexy IP ranges
Response Handling	Must not return card data in responses

Error Handling

curl -X POST https://api.plexypay.com/v2/tokens/tok_card_visa_4242/forward \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "destination_id": "dest_premium_processor",
    "fields": ["card_number", "expiry"]
  }'

If the request fails, the API returns an error object with a code field. Common error codes include destination_not_found, destination_unavailable, destination_rejected, token_not_found, forwarding_disabled, and field_not_available.

Webhooks

Plexy sends webhooks for forwarding events:

`token.forwarded`

Sent when a forward operation completes.

{
  "type": "token.forwarded",
  "data": {
    "id": "fwd_abc123xyz789",
    "token_id": "tok_card_visa_4242",
    "destination_id": "dest_premium_processor",
    "status": "completed",
    "reference": "booking_12345",
    "created_at": "2026-03-25T18:00:00Z"
  }
}

`token.forward_failed`

Sent when a forward operation fails.

{
  "type": "token.forward_failed",
  "data": {
    "id": "fwd_failed_123",
    "token_id": "tok_card_visa_4242",
    "destination_id": "dest_premium_processor",
    "status": "failed",
    "error": {
      "code": "destination_unavailable",
      "message": "Connection timeout to destination endpoint"
    },
    "created_at": "2026-03-25T18:05:00Z"
  }
}

Testing

Use test tokens and the test destination to verify your integration:

Test Destination	Behavior
`dest_test_success`	Always succeeds
`dest_test_timeout`	Simulates timeout
`dest_test_reject`	Simulates rejection
`dest_test_error`	Simulates server error

# Test successful forward
curl -X POST https://api.plexypay.com/v2/tokens/tok_test_visa/forward \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "destination_id": "dest_test_success",
    "fields": ["card_number", "expiry"]
  }'

# Test timeout handling
curl -X POST https://api.plexypay.com/v2/tokens/tok_test_visa/forward \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "destination_id": "dest_test_timeout",
    "fields": ["card_number"]
  }'

Best Practices

Minimize forwarded fields - Only request the fields the destination actually needs
Use references - Always include a reference to correlate with your records
Handle failures gracefully - Implement retry logic for transient errors
Monitor usage - Track forwarding patterns and investigate anomalies
Review destinations regularly - Ensure all registered destinations are still needed and compliant
Audit access - Regularly review who has access to forwarding capabilities

Compliance Considerations

Forward Payment Details involves sharing cardholder data with third parties. Ensure you have appropriate data processing agreements and customer consent where required by applicable regulations (GDPR, PCI DSS, etc.).

PCI DSS Requirements

When using Forward Payment Details:

You must maintain your own PCI DSS compliance
Document all third parties receiving cardholder data
Ensure third parties are included in your annual PCI assessment
Implement appropriate logging and monitoring

Data Protection

Obtain customer consent before sharing payment data with third parties
Document the legal basis for data sharing
Ensure third parties have appropriate data protection measures

Next Steps

Tokenization Overview - Review tokenization concepts
Compliance - Learn about PCI compliance requirements
API Reference - Full API documentation

Forward Payment Details

On this page