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.

// Example: Route high-value transactions to a different processor
if (amount > 100000) {
  await plexy.tokens.forward(tokenId, {
    destination: 'dest_premium_processor',
    // Card data is forwarded to the premium processor
  });
} else {
  // Process normally through Plexy
  await plexy.payments.create({ token_id: tokenId, amount });
}

Fraud Prevention Services

Send card details to specialized fraud detection services before processing.

// Forward to fraud detection service
const fraudCheck = await plexy.tokens.forward(tokenId, {
  destination: 'dest_fraud_service',
  include_metadata: true,
});

if (fraudCheck.ripr_score < 70) {
  // Proceed with payment
  await plexy.payments.create({ token_id: tokenId, amount });
}

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: Bearer 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"
    }
  }'

import { Plexy } from '@plexy/plexy-web';

const plexy = new Plexy({
  apiKey: process.env.PLEXY_SECRET_KEY,
});

const result = await plexy.tokens.forward('tok_card_visa_4242', {
  destination_id: 'dest_premium_processor',
  fields: ['card_number', 'expiry', 'cardholder_name'],
  reference: 'booking_12345',
  metadata: {
    booking_id: 'BK-2026-12345',
    guest_name: 'John Smith',
  },
});

console.log('Forward ID:', result.id);
console.log('Status:', result.status);
console.log('Third-party reference:', result.destination_reference);

import os
from plexy import Plexy

plexy = Plexy(api_key=os.environ['PLEXY_SECRET_KEY'])

result = plexy.tokens.forward(
    'tok_card_visa_4242',
    destination_id='dest_premium_processor',
    fields=['card_number', 'expiry', 'cardholder_name'],
    reference='booking_12345',
    metadata={
        'booking_id': 'BK-2026-12345',
        'guest_name': 'John Smith',
    },
)

print(f'Forward ID: {result.id}')
print(f'Status: {result.status}')
print(f'Third-party reference: {result.destination_reference}')

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: Bearer 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"
      }
    }
  }'

const result = await plexy.tokens.forward('tok_card_visa_4242', {
  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',
    },
  },
});

result = plexy.tokens.forward(
    'tok_card_visa_4242',
    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: Bearer YOUR_API_KEY"

const forwards = await plexy.tokens.listForwards('tok_card_visa_4242');

forwards.data.forEach(forward => {
  console.log(`${forward.id}: ${forward.destination_id} - ${forward.status}`);
});

forwards = plexy.tokens.list_forwards('tok_card_visa_4242')

for forward in forwards.data:
    print(f'{forward.id}: {forward.destination_id} - {forward.status}')

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: Bearer YOUR_API_KEY"

const forward = await plexy.forwards.retrieve('fwd_abc123xyz789');

console.log('Destination response:', forward.destination_response);

forward = plexy.forwards.retrieve('fwd_abc123xyz789')

print(f'Destination response: {forward.destination_response}')

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

import { PlexyError } from '@plexy/plexy-web';

try {
  const result = await plexy.tokens.forward('tok_card_visa_4242', {
    destination_id: 'dest_premium_processor',
    fields: ['card_number', 'expiry'],
  });
} catch (error) {
  if (error instanceof PlexyError) {
    switch (error.code) {
      case 'destination_not_found':
        console.error('Destination is not registered');
        break;
      case 'destination_unavailable':
        console.error('Third party endpoint is not responding');
        break;
      case 'destination_rejected':
        console.error('Third party rejected the request:', error.details);
        break;
      case 'token_not_found':
        console.error('Token does not exist');
        break;
      case 'forwarding_disabled':
        console.error('Forwarding is not enabled for your account');
        break;
      case 'field_not_available':
        console.error('Requested field is not stored for this token');
        break;
      default:
        console.error('Forward failed:', error.message);
    }
  }
}

from plexy import PlexyError

try:
    result = plexy.tokens.forward(
        'tok_card_visa_4242',
        destination_id='dest_premium_processor',
        fields=['card_number', 'expiry'],
    )
except PlexyError as error:
    if error.code == 'destination_not_found':
        print('Destination is not registered')
    elif error.code == 'destination_unavailable':
        print('Third party endpoint is not responding')
    elif error.code == 'destination_rejected':
        print(f'Third party rejected the request: {error.details}')
    elif error.code == 'token_not_found':
        print('Token does not exist')
    elif error.code == 'forwarding_disabled':
        print('Forwarding is not enabled for your account')
    elif error.code == 'field_not_available':
        print('Requested field is not stored for this token')
    else:
        print(f'Forward failed: {error.message}')

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
const result = await plexy.tokens.forward('tok_test_visa', {
  destination_id: 'dest_test_success',
  fields: ['card_number', 'expiry'],
});
// result.status === 'completed'

// Test timeout handling
try {
  await plexy.tokens.forward('tok_test_visa', {
    destination_id: 'dest_test_timeout',
    fields: ['card_number'],
  });
} catch (error) {
  // error.code === 'destination_unavailable'
}

# Test successful forward
result = plexy.tokens.forward(
    'tok_test_visa',
    destination_id='dest_test_success',
    fields=['card_number', 'expiry'],
)
# result.status == 'completed'

# Test timeout handling
try:
    plexy.tokens.forward(
        'tok_test_visa',
        destination_id='dest_test_timeout',
        fields=['card_number'],
    )
except PlexyError as error:
    # error.code == 'destination_unavailable'
    pass

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