---
title: "Forward payment details"
description: "Forward stored payment details to use them with different payment service providers."
url: "https://docs.adyen.com/online-payments/tokenization/forward-payment-details"
source_url: "https://docs.adyen.com/online-payments/tokenization/forward-payment-details.md"
canonical: "https://docs.adyen.com/online-payments/tokenization/forward-payment-details"
last_modified: "2025-06-06T15:30:00+02:00"
language: "en"
---

# Forward payment details

Forward stored payment details to use them with different payment service providers.

[View source](/online-payments/tokenization/forward-payment-details.md)

You can forward payment details that you stored with Adyen to a [PCI compliant](/get-started-with-adyen/adyen-glossary/#pci-compliance) third party, like a payment service provider (PSP). We support forwarding card details, and network tokens.

## Requirements

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

| Requirement                                                               | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| ------------------------------------------------------------------------- |   |
| **Integration type**                                                      | An [online payments integration](/online-payments/build-your-integration/) that uses Checkout API v70 or later.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| **[API credential roles](/development-resources/api-credentials/roles/)** | Make sure that you have the following role(s):- **Checkout webservice role**
- **Merchant Recurring role**                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| **[Webhooks](/development-resources/webhooks)**                           | Subscribe to the [**Recurring tokens life cycle events** webhook](/development-resources/webhooks/webhook-types/#other-webhooks).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| **Limitations**                                                           | To forward network tokens, you must [create a token](/online-payments/tokenization/create-tokens) with Adyen for the same payment details. This is to ensure that Adyen can forward the payment details by falling back to the Adyen token in case we cannot find a network token.                                                                                                                                                                                                                                                                                                                                                                                        |
| **Setup steps**                                                           | Before you begin:- [Create tokens](/online-payments/tokenization/create-tokens) with Adyen.
- If you want to forward network tokens, [implement network tokenization](/online-payments/network-tokenization).
- Contact our [Support Team](https://ca-test.adyen.com/ca/ca/contactUs/support.shtml?form=other) to enable forwarding card details or network tokens.
- Make sure that your [live endpoint](/development-resources/live-endpoints) region matches your Adyen token vault storage region. If you are not sure about the region where your tokens are stored, contact our [Support Team](https://ca-test.adyen.com/ca/ca/contactUs/support.shtml?form=other). |

## How it works

1. You make a POST [/forward](https://docs.adyen.com/api-explorer/Checkout/latest/post/forward) request, 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](#handle-the-result) that contains the third party response as a string.

![](/user/pages/docs/02.online-payments/20.tokenization/05.forward-payment-details/forward-api.svg?decoding=auto\&fetchpriority=auto)

You can forward [card details](#card-details) or [network tokens](#network-tokens).

## Forward card details

We support the following flows to forward card details:

* **Forward a token**: Forward the card details using a token, to share the stored payment details from the Adyen Vault with a third party.
* **Forward a token, with [CVC](/get-started-with-adyen/adyen-glossary#card-security-code-cvc-cvv-cid)**: Forward the card details using a token and the card CVC, to share the stored payment details from the Adyen Vault with a third party,
* **Forward non-tokenized card details**: Forward the card details (encrypted or unencrypted) directly to a third party to let the third party tokenize the card details. Optionally, you can choose to [tokenize](/get-started-with-adyen/adyen-glossary#tokenization) the card with Adyen using the same request.

To forward card details:

1. You make a [request to Adyen](#request-to-adyen-card) including the payment details that you want to forward to the third party.
2. [Adyen makes a request to the third party](#request-to-third-party-card) that contains the payment details.
3. [Third party responds to Adyen](#third-party-response-card), 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](https://docs.adyen.com/api-explorer/Checkout/latest/post/forward) request, specifying:

| Parameter name          | Required                                                                                                                                                | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |   |
| `merchantAccount`       | ![Required](/user/pages/reuse/image-library/01.icons/required/required.svg?decoding=auto\&fetchpriority=auto)                                           | Your merchant account name.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| `shopperReference`      | ![Required](/user/pages/reuse/image-library/01.icons/required/required.svg?decoding=auto\&fetchpriority=auto)                                           | Your unique reference for the shopper.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| `storedPaymentMethodId` | ![Conditionally required](/user/pages/reuse/image-library/01.icons/conditionally-required/conditionally-required.svg?decoding=auto\&fetchpriority=auto) | **Use case**: Include when you are forwarding a token that you have already stored with Adyen. Skip this when forwarding non-tokenized card details. The unique identifier for the token. This is the `storedPaymentMethodId` you received in the [recurring.token.created](https://docs.adyen.com/api-explorer/Tokenization-webhooks/latest/post/recurring.token.created) webhook when you [created the token](/online-payments/tokenization/create-tokens).                                                                                                                                                                                                                        |
| `paymentMethod`         | ![Conditionally required](/user/pages/reuse/image-library/01.icons/conditionally-required/conditionally-required.svg?decoding=auto\&fetchpriority=auto) | **Use cases**:- When forwarding non-tokenized card details, you can include the following fields. The required fields depend on the third party that is receiving the card details:

  * `holderName`
  * `number` / `encryptedCardNumber`
  * `expiryMonth` / `encryptedExpiryMonth`
  * `expiryYear` / `encryptedExpiryYear`
  * `cvc` / `encryptedSecurityCode`

- When forwarding a token with CVC, you can include the CVC. You must also include the `{{securityCode}}` [placeholder](#placeholders) in the `request.body`. The object that contains the encrypted or unencrypted (if you are fully [PCI compliant](/development-resources/pci-dss-compliance-guide)) details. |
| `merchantReference`     |                                                                                                                                                         | Your reference to uniquely identify the transaction.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| `baseUrl`               | ![Required](/user/pages/reuse/image-library/01.icons/required/required.svg?decoding=auto\&fetchpriority=auto)                                           | The base URL of the third party API, where Adyen will send the request to forward the payment details.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| `request.httpMethod`    | ![Required](/user/pages/reuse/image-library/01.icons/required/required.svg?decoding=auto\&fetchpriority=auto)                                           | The HTTP method to use for the request to the third party, for example, **post**, **patch**, or **put**.Use the documentation from the third party to learn about the HTTP method you must use.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| `request.urlSuffix`     | ![Required](/user/pages/reuse/image-library/01.icons/required/required.svg?decoding=auto\&fetchpriority=auto)                                           | 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`   | ![Required](/user/pages/reuse/image-library/01.icons/required/required.svg?decoding=auto\&fetchpriority=auto)                                           | Your credentials for the third party.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| `request.headers`       | ![Required](/user/pages/reuse/image-library/01.icons/required/required.svg?decoding=auto\&fetchpriority=auto)                                           | The request headers to include in the request to the third party, for example, **externalparty-version**, or **authorization**.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| `request.body`          | ![Required](/user/pages/reuse/image-library/01.icons/required/required.svg?decoding=auto\&fetchpriority=auto)                                           | 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](#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.                                                                                                                                                                                                                                             |
| `options.tokenize`      |                                                                                                                                                         | When you are forwarding non-tokenized card details, set to **true** to store the payment details with Adyen using the same request. When set to **true** you must provide the holder name, number, expiry month, and the expiry year of the card in the `paymentMethod` object.                                                                                                                                                                                                                                                                                                                                                                                                      |
| `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**.                                                                                                                                                                                                                                                                                                                                                                          |

![This is the required icon.](/user/pages/reuse/image-library/01.icons/requirements-legend/required.svg?decoding=auto\&fetchpriority=auto) Required for all transactions.\
![This is the conditionally required icon.](/user/pages/reuse/image-library/01.icons/requirements-legend/conditionally-required.svg?decoding=auto\&fetchpriority=auto) Required for particular setups, or issuers and card schemes.\
![This is the recommended icon.](/user/pages/reuse/image-library/01.icons/requirements-legend/recommended.svg?decoding=auto\&fetchpriority=auto) Recommended for all transactions, but not required.

Depending on the forwarding flow you are using, what to include in your request changes. The examples below show how to construct your request for each flow.

### Tab: Forward a token

**Example request to forward a token**

```bash
curl https://checkout-test.adyen.com/v71/forward \
-H 'x-api-key: ADYEN_API_KEY' \
-H 'content-type: application/json' \
-d '{
  "merchantAccount": "YOUR_MERCHANT_ACCOUNT",
  "shopperReference": "YOUR_SHOPPER_REFERENCE",
  "storedPaymentMethodId": "M5N7TQ4TG5PFWR50",
  "merchantReference": "YOUR_UNIQUE_REFERENCE",
  "baseUrl": "http://thirdparty.example.com",
  "request": {
     "httpMethod": "post",
     "urlSuffix": "/payments",
     "credentials": "YOUR_CREDENTIALS_FOR_THE_THIRD_PARTY",
     "headers": {
        "Authorization": "Basic {​{credentials}}"
     },
     "body": "{
        "amount": {
            "value": 100,
            "currency": "USD"
        },
        "paymentMethod": {
           "creditCard": {
                "holderName": "{​{holderName}}",
                "number": "{​{number}}",
                "expiryMonth": "{​{expiryMonth}}",
                "expiryYear": "{​{expiryYear}}"
           }
        }
     }"
  }
}'
```

### Tab: Forward a token, with CVC

**Example request to forward a token, with CVC**

```bash
curl https://checkout-test.adyen.com/v71/forward \
-H 'x-api-key: ADYEN_API_KEY' \
-H 'content-type: application/json' \
-d '{
  "merchantAccount": "YOUR_MERCHANT_ACCOUNT",
  "shopperReference": "YOUR_SHOPPER_REFERENCE",
  "storedPaymentMethodId": "M5N7TQ4TG5PFWR50",
  "paymentMethod": {
     "cvc": "737",
  "baseUrl": "http://thirdparty.example.com",
  "request": {
     "httpMethod": "post",
     "urlSuffix": "/payments",
     "credentials": "YOUR_CREDENTIALS_FOR_THE_THIRD_PARTY",
     "headers": {
        "Authorization": "Basic {​{credentials}}"
     },
     "body": "{
        "amount": {
            "value": 100,
            "currency": "USD"
        },
        "paymentMethod": {
           "creditCard": {
                "holderName": "{​{holderName}}",
                "number": "{​{number}}",
                "expiryMonth": "{​{expiryMonth}}",
                "expiryYear": "{​{expiryYear}}"
                "cvc": "{​{securityCode}}"
           }
        }
     }"
  }
}'
```

### Tab: Forward card details

**Example request to forward card details**

```bash
curl https://checkout-test.adyen.com/v71/forward \
-H 'x-api-key: ADYEN_API_KEY' \
-H 'content-type: application/json' \
-d '{
  "merchantAccount": "YOUR_MERCHANT_ACCOUNT",
  "shopperReference": "YOUR_SHOPPER_REFERENCE",
  "merchantReference": "YOUR_UNIQUE_REFERENCE",
  "paymentMethod": {
     "type": "scheme",
     "number": "4111111111111111",
     "expiryMonth": "03",
     "expiryYear": "2030",
     "cvc": "737",
     "holderName": "S. Hopper"
  }
  "baseUrl": "http://thirdparty.example.com",
  "request": {
     "httpMethod": "post",
     "urlSuffix": "/payments",
     "credentials": "YOUR_CREDENTIALS_FOR_THE_THIRD_PARTY",
     "headers": {
        "Authorization": "Basic {​{credentials}}"
     },
     "body": "{
        "amount": {
            "value": 100,
            "currency": "USD"
        }
     }"
  }
}'
```

### 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](https://docs.adyen.com/api-explorer/Checkout/latest/post/forward#request-baseUrl) and [request.urlSuffix](https://docs.adyen.com/api-explorer/Checkout/latest/post/forward#request-request-urlSuffix) you provided in your forwarding request. The code sample below shows the request Adyen would make to the third party for forwarding a token, without CVC.

**Example request from Adyen to third party**

```bash
curl https://thirdparty.example.com/payments \
-H "Basic merchant:pass" \
-H 'content-type: application/json' \
-d '{
   "amount": {
      "value": 100,
      "currency": "USD"
   },
  "paymentMethod": {
     "creditCard": {
        "holderName": "S. Hopper",
        "number": "4111111111111111",
        "expiryMonth": "12",
        "expiryYear": "2025"
     }
  }
}'
```

### Third party responds to Adyen

We receive a response from the third party that contains the outcome of the [/forward](https://docs.adyen.com/api-explorer/Checkout/latest/post/forward) request. The response structure and content can differ depending on the third party.

**Example response from third party to Adyen**

```bash
{
  "data": {
     "tokenizeCreditCard": {
        "paymentMethod": {
           "id": "PAYMENT_METHOD_ID"
        }
     }
  }
}
```

## Forward network tokens

To forward stored network tokens:

1. You make a POST [/forward](https://docs.adyen.com/api-explorer/Checkout/latest/post/forward) request, including the `options.networkToken` parameter to [forward a network token](#request-to-adyen-network).
2. In your request, you specify [a fallback logic](#build-logic-for-adyen-token-fallback) 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](#request-to-third-party-network) that contains the payment details.
4. [Third party responds to Adyen](#third-party-response-network), and we forward this response to you.

When building your logic for network tokens, keep in mind that you can not forward a network token together with card details that are not yet tokenized by Adyen.

### 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](https://docs.adyen.com/api-explorer/Checkout/latest/post/forward) request, specifying:

| Parameter name          | Required                                                                                                                                                | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |   |
| `merchantAccount`       | ![Required](/user/pages/reuse/image-library/01.icons/required/required.svg?decoding=auto\&fetchpriority=auto)                                           | Your merchant account name.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| `shopperReference`      | ![Required](/user/pages/reuse/image-library/01.icons/required/required.svg?decoding=auto\&fetchpriority=auto)                                           | Your unique reference for the shopper.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| `storedPaymentMethodId` | ![Conditionally required](/user/pages/reuse/image-library/01.icons/conditionally-required/conditionally-required.svg?decoding=auto\&fetchpriority=auto) | **Use case**: Include when you are forwarding a token that you have already stored with Adyen. Skip this when forwarding non-tokenized card details. The unique identifier for the token. This is the `storedPaymentMethodId` you received in the [recurring.token.created](https://docs.adyen.com/api-explorer/Tokenization-webhooks/latest/post/recurring.token.created) webhook when you [created the token](/online-payments/tokenization/create-tokens).                                                                                                                                                                                                                                                                                                                                                        |
| `paymentMethod`         | ![Conditionally required](/user/pages/reuse/image-library/01.icons/conditionally-required/conditionally-required.svg?decoding=auto\&fetchpriority=auto) | **Use cases**:- When forwarding non-tokenized card details, you can include the following fields. The required fields depend on the third party that is receiving the card details:

  * `holderName`
  * `number` / `encryptedCardNumber`
  * `expiryMonth` / `encryptedExpiryMonth`
  * `expiryYear` / `encryptedExpiryYear`
  * `cvc` / `encryptedSecurityCode`

- When forwarding a token with CVC, you can include the CVC. You must also include the `{{securityCode}}` [placeholder](#placeholders) in the `request.body`. The object that contains the encrypted or unencrypted (if you are fully [PCI compliant](/development-resources/pci-dss-compliance-guide)) details.                                                                                                                                 |
| `merchantReference`     |                                                                                                                                                         | Your reference to uniquely identify the transaction.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| `baseUrl`               | ![Required](/user/pages/reuse/image-library/01.icons/required/required.svg?decoding=auto\&fetchpriority=auto)                                           | The base URL of the third party API, where Adyen will send the request to forward the payment details.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| `request.httpMethod`    | ![Required](/user/pages/reuse/image-library/01.icons/required/required.svg?decoding=auto\&fetchpriority=auto)                                           | The HTTP method to use for the request to the third party, for example, **post**, **patch**, or **put**.Use the documentation from the third party to learn about the HTTP method you must use.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| `request.urlSuffix`     | ![Required](/user/pages/reuse/image-library/01.icons/required/required.svg?decoding=auto\&fetchpriority=auto)                                           | 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`   | ![Required](/user/pages/reuse/image-library/01.icons/required/required.svg?decoding=auto\&fetchpriority=auto)                                           | Your credentials for the third party.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| `request.headers`       | ![Required](/user/pages/reuse/image-library/01.icons/required/required.svg?decoding=auto\&fetchpriority=auto)                                           | The request headers to include in the request to the third party, for example, **externalparty-version**, or **authorization**.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| `request.body`          | ![Conditionally required](/user/pages/reuse/image-library/01.icons/conditionally-required/conditionally-required.svg?decoding=auto\&fetchpriority=auto) | 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](#conditional-placeholders) 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](https://github.com/spullara/mustache.java) syntax for conditions.
- Key value pairs that use [placeholders](#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. |
| `options.networkToken`  | ![Conditionally required](/user/pages/reuse/image-library/01.icons/conditionally-required/conditionally-required.svg?decoding=auto\&fetchpriority=auto) | **Use case**: Required to forward a network token. 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.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| `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**.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |

![This is the required icon.](/user/pages/reuse/image-library/01.icons/requirements-legend/required.svg?decoding=auto\&fetchpriority=auto) Required for all transactions.\
![This is the conditionally required icon.](/user/pages/reuse/image-library/01.icons/requirements-legend/conditionally-required.svg?decoding=auto\&fetchpriority=auto) Required for particular setups, or issuers and card schemes.\
![This is the recommended icon.](/user/pages/reuse/image-library/01.icons/requirements-legend/recommended.svg?decoding=auto\&fetchpriority=auto) Recommended for all transactions, but not required.

### Build logic for Adyen token fallback

For requests that include network tokens, you must add a conditional statement in your [`/forward` request to Adyen](#request-to-adyen-network).

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 | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | Forward the network token, `networkTxReference`, and the network token cryptogram. |
| Scenario 2 | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | ![-x-](/user/data/smileys/emoji/x.png "-x-")                                                | ![-x-](/user/data/smileys/emoji/x.png "-x-")                                                | Forward the network token.                                                         |
| Scenario 3 | ![-x-](/user/data/smileys/emoji/x.png "-x-")                                                | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | ![-x-](/user/data/smileys/emoji/x.png "-x-")                                                | Fallback to the Adyen token.                                                       |

**Example request to forward a network token**

```bash
curl https://checkout-test.adyen.com/v71/forward \
-H 'x-api-key: ADYEN_API_KEY' \
-H 'content-type: application/json' \
-d '{
  "merchantAccount": "YOUR_MERCHANT_ACCOUNT",
  "shopperReference": "YOUR_SHOPPER_REFERENCE",
  "storedPaymentMethodId": "M5N7TQ4TG5PFWR50",
  "merchantReference": "YOUR_UNIQUE_REFERENCE",
  "baseUrl": "http://thirdparty.example.com",
   "options" : {
      "networkToken":{
         "useNetworkToken":true,
         "includeCryptogram":true
      }
   },
  "request": {
     "httpMethod": "post",
     "urlSuffix": "/payments",
     "credentials": "YOUR_CREDENTIALS_FOR_THE_THIRD_PARTY",
     "headers": {
        "Authorization": "Basic {​{credentials}}"
     },
     "body": "{
        "amount": {
           "value": 100,
           "currency": "USD"
        }
        {​{​#networkTxReference}},
            "reference": "{​{​networkTxReference}}"
        {​{/networkTxReference}}
        {​{​#networkTokenExists}},
            "networkToken": {
                "number": "{​{tokenNumber}}",
                "expiryMonth": "{​{tokenExpiryMonth}}",
                "expiryYear": "{​{tokenExpiryYear}}"
                {​{​#cryptogram}}",
                    "eci": "{​{ecommerceIndicator}}",
                    "cryptogram": "{​{cryptogram}}"
                {​{/cryptogram}}"
            }
        {​{/networkTokenExists}}
        {​{^networkTokenExists}},
            "paymentMethod": {
                "holderName": "{​{holderName}}",
                "number": "{​{number}}",
                "expiryMonth": "{​{expiryMonth}}",
                "expiryYear": "{​{expiryYear}}"
            }
        {​{/networkTokenExists}}
     }"
  }
}'
```

### 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](https://docs.adyen.com/api-explorer/Checkout/latest/post/forward#request-baseUrl) and [request.urlSuffix](https://docs.adyen.com/api-explorer/Checkout/latest/post/forward#request-request-urlSuffix) you provided in your forwarding request.

We use the [condition](#conditional-placeholders) you set in the [/forward](https://docs.adyen.com/api-explorer/Checkout/latest/post/forward) field to determine which details to forward to the third party.

### Tab: Scenario 1

The network token, `networkTxReference`, and the cryptogram are found. Adyen forwards all details to the third party.

**Example request from Adyen to third party including all details**

```bash
curl https://thirdparty.example.com/payments \
-H "Basic merchant:pass" \
-H 'content-type: application/json' \
-d '{
   "amount": {
      "value": 100,
      "currency": "USD"
   },
   "reference": "5252520200034065",
   "networkToken" : {
      "expiryMonth" : "12",
      "expiryYear" : "2024",
      "number" : "4111111111111111",
      "eci":"02",
      "cryptogram":"123"
   }
}'
```

### Tab: Scenario 2

The network token is found, but a `networkTxReference` is not found. Adyen only forwards the network token to the third party.

**Example request from Adyen to third party including a network token**

```bash
curl https://thirdparty.example.com/payments \
-H "Basic merchant:pass" \
-H 'content-type: application/json' \
-d '{
   "amount": {
      "value": 100,
      "currency": "USD"
   },
   "networkToken" : {
      "expiryMonth" : "12",
      "expiryYear" : "2024",
      "number" : "4111111111111111",
   }
}'
```

### Tab: Scenario 3

A network token is not found. Adyen uses the card details that you stored with [Adyen tokenization](/online-payments/tokenization) to forward payment details to the third party.

**Example request from Adyen to third party including card details**

```bash
curl https://thirdparty.example.com/payments \
-H "Basic merchant:pass" \
-H 'content-type: application/json' \
-d '{
   "amount": {
      "value": 100,
      "currency": "USD"
   },
  "reference": "5252520200034065",
  "paymentMethod": {
     "holderName": "S. Hopper",
     "number": "4111111111111111",
     "expiryMonth": "12",
     "expiryYear": "2025"
  }
}'
```

### 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.

**Example response from third party to Adyen**

```bash
{
  "data": {
     "tokenizeCreditCard": {
        "paymentMethod": {
           "id": "PAYMENT_METHOD_ID"
        }
     }
  }
}
```

## Handle the result

You receive a response from Adyen that informs you of the outcome of your [/forward](https://docs.adyen.com/api-explorer/Checkout/latest/post/forward) request, for example:

**Example /forward response from Adyen**

```bash
{
   "storedPaymentMethodId": "M5N7TQ4TG5PFWR50",
   "pspReference": "XB7XNCQ8HXSKGK82",
   "merchantReference": "YOUR_REFERENCE"
   "response": {
     "status": 200,
     "headers": {
        "thirdparty-version": "2023-10-16"
     },
     "body": "{\"success\": \"ok\",\"data\": {\"tokenizeCreditCard\": {\"paymentMethod\": {\"id\": \"PAYMENT_METHOD_ID\"}}}}"
   }
}
```

The response contains:

* `pspReference`: Our unique identifier for the transaction.
* `merchantReference`: The unique reference for the transaction that you included in your request to forward payment details.
* `storedPaymentMethodId`: The unique identifier for the stored payment details that were forwarded. This is the Adyen identifier.\
  This field is not returned if you [forward non-tokenized card details](#card-details), and set `options.tokenize` to **false**.
* `response.status`: The [HTTP status code](/development-resources/response-handling/) Adyen received from the third party.
* `response.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](/development-resources/response-handling/) different from **2XX**. In this response, you get an [error code and message](/development-resources/error-codes/) 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](/development-resources/response-handling#http-responses) 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](/development-resources/error-codes/#803-paymentdetail-not-found):

**Error details in API response**

```bash
{
    "status": 422,
    "errorCode": "803",
    "message": "PaymentDetail not found",
    "errorType": "validation"
}
```

## 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.

| Placeholder                            | Use case(s)                                                                        | Description                                                                                                                                                                                                                                                                                                                |
| -------------------------------------- | ---------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `{{credentials}}`                      | [Card details](#request-to-adyen-card) [Network tokens](#request-to-adyen-network) | The credentials to authenticate the API request.                                                                                                                                                                                                                                                                           |
| `{{number}}`                           | [Card details](#request-to-adyen-card) [Network tokens](#request-to-adyen-network) | The card number.                                                                                                                                                                                                                                                                                                           |
| `{{expiryMonth}}`                      | [Card details](#request-to-adyen-card) [Network tokens](#request-to-adyen-network) | Expiry month of the card.                                                                                                                                                                                                                                                                                                  |
| `{{expiryYear}}`                       | [Card details](#request-to-adyen-card) [Network tokens](#request-to-adyen-network) | Expiry year of the card.                                                                                                                                                                                                                                                                                                   |
| `{{expiryYearYY}}`                     | [Card details](#request-to-adyen-card) [Network tokens](#request-to-adyen-network) | Expiry year of the card. Use this field if you want to send a two-digit value for the expiry year.                                                                                                                                                                                                                         |
| `{{securityCode}}`                     | [Card details](#request-to-adyen-card) [Network tokens](#request-to-adyen-network) | The security code (CVC) of the card.                                                                                                                                                                                                                                                                                       |
| `{{billingaddress.street}}`            | [Card details](#request-to-adyen-card) [Network tokens](#request-to-adyen-network) | The billing address street stored along with the token.                                                                                                                                                                                                                                                                    |
| `{{billingaddress.housenumberorname}}` | [Card details](#request-to-adyen-card) [Network tokens](#request-to-adyen-network) | The billing address house number/name stored with the token.                                                                                                                                                                                                                                                               |
| `{{billingaddress.postalcode}}`        | [Card details](#request-to-adyen-card) [Network tokens](#request-to-adyen-network) | The billing address postcode/ZIP code stored with the token.                                                                                                                                                                                                                                                               |
| `{{billingaddress.stateorprovince}}`   | [Card details](#request-to-adyen-card) [Network tokens](#request-to-adyen-network) | The billing address state/province field stored with the token.                                                                                                                                                                                                                                                            |
| `{{billingaddress.city}}`              | [Card details](#request-to-adyen-card) [Network tokens](#request-to-adyen-network) | The billing address city stored with the token.                                                                                                                                                                                                                                                                            |
| `{{billingaddress.countrycode}}`       | [Card details](#request-to-adyen-card) [Network tokens](#request-to-adyen-network) | The billing address country code stored with the token.                                                                                                                                                                                                                                                                    |
| `{{billingaddress.addressline3}}`      | [Card details](#request-to-adyen-card) [Network tokens](#request-to-adyen-network) | The billing address additional line stored with the token.                                                                                                                                                                                                                                                                 |
| `{{holderName}}`                       | [Card details](#request-to-adyen-card)                                             | The card holder's name.                                                                                                                                                                                                                                                                                                    |
| `{{networkTxReference}}`               | [Network tokens](#request-to-adyen-network) [Card details](#request-to-adyen-card) | The transaction identifier from card schemes that allows you to link the transaction to the original or previous one for recurring payments.                                                                                                                                                                               |
| `{{transactionLinkId}}`                | [Network tokens](#request-to-adyen-network) [Card details](#request-to-adyen-card) | The [Mastercard Transaction Link Identifier](https://help.adyen.com/updates/mastercard-transaction-link-identifier-tlid). This identifier has the same purpose as the `{{networkTxReference}}`, but is used for Mastercard specifically. You can provide both identifiers in the same transaction, or provide one of them. |
| `{{tokenNumber}}`                      | [Network tokens](#request-to-adyen-network)                                        | The 16-digit alternative for the Primary Account Number (PAN).                                                                                                                                                                                                                                                             |
| `{{tokenExpiryMonth}}`                 | [Network tokens](#request-to-adyen-network)                                        | Expiry month of the network token.                                                                                                                                                                                                                                                                                         |
| `{{tokenExpiryYear}}`                  | [Network tokens](#request-to-adyen-network)                                        | Expiry year of the network token.                                                                                                                                                                                                                                                                                          |
| `{{tokenExpiryYearYY}}`                | [Network tokens](#request-to-adyen-network)                                        | Expiry year of the network token. Use this field if you want to send a two-digit value for the expiry year.                                                                                                                                                                                                                |
| `{{cryptogram}}`                       | [Network tokens](#request-to-adyen-network)                                        | The single-use key that enables to use the network token for a transaction.                                                                                                                                                                                                                                                |
| `{{ecommerceIndicator}}`               | [Network tokens](#request-to-adyen-network)                                        | The Electronic Commerce Indicator of the cryptogram, returned from the schemes.                                                                                                                                                                                                                                            |

## See also

* [Create tokens](/online-payments/tokenization/create-tokens)
* [Manage tokens](/online-payments/tokenization/managing-tokens)
* [Network tokenization](/online-payments/network-tokenization)
* [Cards](/payment-methods/cards)
