Forward payment details

You can forward payment details that you stored with Adyen to a PCI compliant third party, such as another payment service provider. This lets you use the payment details you have securely stored with Adyen across providers. We support forwarding:

• Card details that you have tokenized with Adyen.
• Network tokens.

Requirements

Before you begin, take into account the following requirements, limitations, and preparations.

How it works

1. You make a POST /forward request to the Adyen Checkout API, including placeholders for the payment details you want to forward and the destination.
2. Adyen replaces the placeholders with the payment details and makes a request to the third party API on your behalf to forward the payment details.
3. Adyen receives a response from the third party.
4. You receive a response from Adyen that contains the third party response as a string.

You can use the /forward endpoint to forward card details or network tokens. Follow the steps for the flow you want to use:

• Forward card details
• Forward network tokens

Forward card details

To forward stored card payment details:

1. You make a request to Adyen to forward the stored payment details on your behalf.
2. Adyen makes a request to the third party that contains the stored payment details.
3. Third party responds to Adyen, and we forward this response to you.

Make a forward request to Adyen

To forward the payment details you store with Adyen to a third party, inform Adyen about the payment details that you want to forward and the destination. Adyen uses the information in your request to make a request to the third party on your behalf.

From your server, make a POST /forward request, specifying:

Parameter name	Required	Description
merchantAccount		Your merchant account name.
shopperReference		Your unique reference for the shopper.
storedPaymentMethodId		The unique identifier for the token. This is the storedPaymentMethodId you received in the recurring.token.created webhook when you created the token.
baseUrl		The base URL of the third party API, where Adyen will send the request to forward the payment details.
options.dryRun		Set to true to receive the request body that is populated to forward to the third party in the response. Any sensitive information will be masked in the response you receive. This functionality is only available in the test environment to help you set up your integration, defaults to false.
request.httpMethod		The HTTP method to use for the request to the third party, for example, POST. Use the documentation from the third party to learn about the HTTP method you must use.
request.urlSuffix		The suffix to append to the baseUrl to construct the destination URL for the request to the third party. This is usually the endpoint name for the request, for example, /payments.
request.credentials		Your credentials for the third party.
request.headers		The request headers to include in the request to the third party, for example, externalparty-version, or authorization.
request.body		The request body that you want Adyen to forward to the third party on your behalf, in string format. Include key value pairs to specify the payment details, and use placeholders for the values. Adyen replaces the placeholders with the payment details when making the request to the third party. Use the documentation from the third party to learn about the parameters you need to include in the request body.

Adyen makes a request to the third party

We make a request to the third party on your behalf. To construct the endpoint URL, we use the baseUrl and urlSuffix you provided in your /forward request.

Third party responds to Adyen

We receive a response from the third party that contains the outcome of the forward request. The response structure and content can differ depending on the third party.

Forward network tokens

To forward stored network tokens:

1. You make a request to Adyen to forward the network token on your behalf.
2. In your request, you specify a fallback logic to ensure that Adyen can forward the payment details using the token you created with Adyen instead of the network token in case it cannot be found.
3. Adyen makes a request to the third party that contains the stored payment details.
4. Third party responds to Adyen, and we forward this response to you.

Make a request to Adyen

To forward the network tokens you store with Adyen to a third party, inform Adyen about the network token that you want to forward and the destination. Adyen uses the information in your request to make a request to the third party on your behalf.

From your server, make a POST /forward request, specifying:

Parameter name	Required	Description
merchantAccount		Your merchant account name.
shopperReference		Your unique reference for the shopper.
storedPaymentMethodId		The unique identifier for the token. This is the storedPaymentMethodId you received in the recurring.token.created webhook when you created the token.
baseUrl		The base URL of the third party API, where Adyen will send the request to forward the payment details.
options.dryRun		Set to true to receive the request body that is populated to forward to the third party in the response. Any sensitive information will be masked in the response you receive. This functionality is only available in the test environment to help you set up your integration, defaults to false.
options.networkToken		The object that enables forwarding network tokens, including: useNetworkToken: Set to true to enable forwarding network tokens. includeCryptogram: Set to true to enable forwarding network token cryptograms.
request.httpMethod		The HTTP method to use for the request to the third party, for example, POST. Use the documentation from the third party to learn about the HTTP method you must use.
request.urlSuffix		The suffix to append to the baseUrl to construct the destination URL for the request to the third party. This is usually the endpoint name for the request, for example, /payments.
request.credentials		Your credentials for the third party.
request.headers		The request headers to include in the request to the third party, for example, externalparty-version, or authorization.
request.body		The request body that you want Adyen to forward to the third party on your behalf, in string format. In the body, include: A condition that checks if the network token exists, and informs Adyen of which fields to send depending on the outcome. You must inform Adyen to forward card details in case the network token cannot be found. Use Mustache.java syntax for conditions. Key value pairs that use placeholders for the values that specify the payment details to be forwarded. Adyen replaces the placeholders with the payment details when making the request to the third party. Use the documentation from the third party to learn about the parameters you need to include in the request body.

Build logic for Adyen token fallback

For requests that include network tokens, you must add a conditional statement in your /forward request to Adyen.

In your condition, you must build a logic that informs Adyen to check if the network token exists, and determine the fields to forward to the third party depending on the outcome. Your condition must introduce a fallback to forward the token you created for the same payment details with Adyen in case the network token cannot be found.

The following table indicates the fields that must be forwarded to third party depending on different availability scenarios.

	Network token	networkTxReference	Cryptogram	Fields to forward to the third party
Scenario 1				Forward the network token, networkTxReference, and the network token cryptogram.
Scenario 2				Forward the network token.
Scenario 3				Fallback to the Adyen token.

Adyen makes a request to the third party

We make a request to the third party on your behalf. To construct the endpoint URL, we use the baseUrl and urlSuffix you provided in your /forward request.

We use the condition you set in the request.body field to determine which details to forward to the third party.

Third party responds to Adyen

We receive a response from the third party, that contains the outcome of the forward request. The response structure and content can differ, depending on the third party.

Handle the result

You receive a response from Adyen that informs you of the outcome of your /forward request, for example:

The response contains:

• status: The HTTP status code Adyen received from the third party.
• body: The response that Adyen received from the third party. Adyen passes the response as a string without modifying it.

Errors

If Adyen's request to share the token fails, you will receive a response with HTTP status code different from 2XX. In this response, you get an error code and message that help you diagnose and resolve the error.

When you make a request to forward payment details, and an error occurs on the Adyen side, you will receive a response with HTTP status code different from 2XX.

If an error occurs on the third party side, you can receive:

• 502: Third party did not send a response to Adyen.
• 505: Third party experienced a time-out.

Below is an example where the request fails, with status code 422 and error code 803:

Placeholder reference

Use the documentation from the third party to determine the parameters you must include in your /forward request. You must send the parameters in key value pairs, where you use the keys specified by the third party, paired with the placeholder values that Adyen can replace with real values.

The following is a list of placeholders that Adyen can map to real values and forward to a third party. The Use case(s) column specifies the placeholders that are relevant when forwarding card details and network tokens.

See also

• Create tokens
• Manage tokens
• Network tokenization
• Cards