> For the complete documentation index, see [llms.txt](https://docs.payengine.co/payengine-api-v2.5/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.payengine.co/payengine-api-v2.5/transactions/token-exchange.md). # Token Exchange
## Exchange tokens ### **Request** `POST` `https:///api/token-exchange` #### Body Parameters
NameTypeDescription
gateway_idUUIDPlatform gateway ID if required. Not required if gateway type is provided.
payengine_token *stringCard token generated by Platform.
merchant_idUUIDPlatform merchant ID if required.
third_party_name (deprecated)stringDeprecated. Use gateway property instead.
gatewaystring

3rd party gateway type. Can be used along with merchant_id, if you don't know the gateway_id.

Example:

nmi | sierra | viaconex | stripe | elavon | payrix | etc.

/pages/70o5T9ud0WZwUx9fFUIP

third_party_required_dataobjectRequired data (if any) like authentication details for the 3rd party processor.
third_party_additional_dataobjectAny optional values to be sent to the third-party processor for token creation.

Ensure that you adhere to the schema defined by the third-party processor and maintain precise naming conventions.

For example, one of the optional field in the 3rd party processor is firstName, then it can be specified as
third_party_additional_data.firstName in this API request.
metadataobjectSet of key-value pairs that you can attach to an object. This can be useful for storing additional information about the object in a structured format and it will be returned in the response
### Response {% tabs %} {% tab title="Response Object" %} {% tabs %} {% tab title="Card Token Field Definitions" %}
Field NameTypeDescription
data.idstringUnique identified for the card object.
data.third_party_name (deprecated)stringDeprecated. Use gateway instead.
data.gatewaystring

Name of the 3rd party processor, provided in the request.

Example:

nmi | sierra | viaconex | stripe | elavon | payrix | etc.

/pages/70o5T9ud0WZwUx9fFUIP

data.payengine_tokenstringCard token generated by Platform provided in the request.
data.third_party_tokenstringCard token generated by the 3rd party processor for the information provided in the Platform token.
data.third_party_additional_dataobjectReturn the third_party_additional_data from the request.
data.third_party_responseobjectContains the exact response from the third party processor.
metadataobjectReturn the metadata object provided in the request.
errorbooleantrue | false. True when there is an error
errorsobjectReturn the error response from the third party processor.
{% endtab %} {% endtabs %} {% endtab %} {% endtabs %} ### Sample Request and Response {% tabs %} {% tab title="Sample Request" %} ```json curl --location 'https://console.payengine.co/api/token-exchange' \ --header 'Authorization: Basic YOUR_API_KEY' \ --header 'Content-Type: application/json' \ --data '{ "third_party_name": "payrix", "payengine_token": "card_test_D01CXZR5g7rLQNCXjwewiH", "third_party_required_data": { // Example - Payrix API key "apikey": "YOUR_3RD_PARTY_API_KEY" }, "third_party_additional_data": { "firstName": "test" }, "metadata": { "external_id": "ABC123" }, }' ``` {% endtab %} {% tab title="Sample Response - Success" %} ```json { "error": false, "data": { "id": "4335e6c0-947c-4127-a222-a1934ee93bac", "third_party_name": "payrix", "payengine_token": "card_test_D01CXZR5g7rLQNCXmFwCkexY", "third_party_token": "701c08a668b7bc23b117d24c7c45a1c4", "third_party_additional_data": {}, "third_party_response": { "customer": { "id": "t1_cus_66314f1818ae17076ff6471", "created": "2024-04-30 16:05:44.1013", "modified": "2024-04-30 16:05:44.1013", "creator": "t1_log_6439877905f80472399d51c", "modifier": "t1_log_6439877905f80472399d51c", "login": "t1_log_6439877905f80472399d51c", "merchant": null, "first": "helen", "middle": null, "last": "keter" }, "payment": { "id": "g157b215cd94669", "method": 2, "number": "1111", "routing": "0", "bin": "411111", "payment": null, "lastChecked": null, "last4": null, "mask": null }, "id": "t1_tok_66314f181ad7e233504ff28", "created": "2024-04-30 16:05:44.1189", "modified": "2024-04-30 16:05:44.1189", "creator": "t1_log_6439877905f80472399d51c", "modifier": "t1_log_6439877905f80472399d51c", "token": "701c08a668b7bc23b117d24c7c45a1c4", "expiration": "0829", } } ``` {% endtab %} {% tab title="Sample Response - Error" %} Sample Error Response when the Platform Token is wrong ```json { "error": false, "message": "Platform token cannot be found" } ``` Sample Error Response when it is failed at the 3rd party processor ```json { "error": true, "data": { "id": "899ba86b-cb5c-4c8a-b19b-8828899fa3fd", "third_party_name": "payrix", "payengine_token": "card_test_D01CXZR5g7rLQNCXmFwCkexY", "third_party_additional_data": {} }, "errors": { "field": "payment.number", "code": 15, "severity": 2, "msg": "Invalid credit card/debit card number", "error_code": "invalid_card_number" } } ``` {% endtab %} {% endtabs %} ### Third Party Requirements For token exchange with a specific third-party, if you have already configured a corresponding gateway for a merchant (either in our partner portal or with our [Gateway Management](/payengine-api-v2.5/transactions/gateway-orchestration.md) API), then you can provide the Platform gateway ID or merchant ID in the token exchange request in order to map the entities in the third-party to the merchant. #### Payrix {% tabs %} {% tab title="Sample Request" %} **Payload with specific gateway ID** ```bash --header 'Authorization: Basic YOUR_API_KEY' \ --header 'Content-Type: application/json' \ --data '{ "third_party_name": "payrix", "payengine_token": "card_sandbox_D01CXZR5g7rLQNCXjwewiH", "gateway_id": "0c49b17e-9a88-411a-9eda-7e54879055af" }' ``` **Payload with merchant ID** If merchant ID is provided, the system will choose the gateway based on the default enabled gateway for the merchant. ```bash --header 'Authorization: Basic YOUR_API_KEY' \ --header 'Content-Type: application/json' \ --data '{ "third_party_name": "payrix", "payengine_token": "card_sandbox_D01CXZR5g7rLQNCXjwewiH", "merchant_id": "70c799bd-db73-41c3-96af-62b367359b7e" }' ``` {% endtab %} {% tab title="Sample Response - Success" %} ```json { "error": false, "data": { "id": "4335e6c0-947c-4127-a222-a1934ee93bac", "third_party_name": "payrix", "payengine_token": "card_test_D01CXZR5g7rLQNCXmFwCkexY", "third_party_token": "701c08a668b7bc23b117d24c7c45a1c4", "third_party_additional_data": {}, "third_party_response": { "customer": { "id": "t1_cus_66314f1818ae17076ff6471", "created": "2024-04-30 16:05:44.1013", "modified": "2024-04-30 16:05:44.1013", "creator": "t1_log_6439877905f80472399d51c", "modifier": "t1_log_6439877905f80472399d51c", "login": "t1_log_6439877905f80472399d51c", "merchant": null, "first": "helen", "middle": null, "last": "keter" }, "payment": { "id": "g157b215cd94669", "method": 2, "number": "1111", "routing": "0", "bin": "411111", "payment": null, "lastChecked": null, "last4": null, "mask": null }, "id": "t1_tok_66314f181ad7e233504ff28", "created": "2024-04-30 16:05:44.1189", "modified": "2024-04-30 16:05:44.1189", "creator": "t1_log_6439877905f80472399d51c", "modifier": "t1_log_6439877905f80472399d51c", "token": "701c08a668b7bc23b117d24c7c45a1c4", "expiration": "0829", } } ``` {% endtab %} {% tab title="Sample Response - Error" %} Sample Error Response when the Platform Token is wrong ```json { "error": false, "message": "Platform token cannot be found" } ``` Sample Error Response when it is failed at the 3rd party processor ```json { "error": true, "data": { "id": "899ba86b-cb5c-4c8a-b19b-8828899fa3fd", "third_party_name": "payrix", "payengine_token": "card_test_D01CXZR5g7rLQNCXmFwCkexY", "third_party_additional_data": {} }, "errors": { "field": "payment.number", "code": 15, "severity": 2, "msg": "Invalid credit card/debit card number", "error_code": "invalid_card_number" } } ``` {% endtab %} {% endtabs %} #### Braintree {% tabs %} {% tab title="Sample Request" %} **Payload with specific gateway ID** ```bash --header 'Authorization: Basic YOUR_API_KEY' \ --header 'Content-Type: application/json' \ --data '{ "third_party_name": "braintree", "payengine_token": "card_sandbox_D01CXZR5g7rLQNCXjwewiH", "gateway_id": "0c49b17e-9a88-411a-9eda-7e54879055af" }' ``` **Payload with merchant ID** If merchant ID is provided, the system will choose the gateway based on the default enabled gateway for the merchant. ```bash --header 'Authorization: Basic YOUR_API_KEY' \ --header 'Content-Type: application/json' \ --data '{ "third_party_name": "braintree", "payengine_token": "card_sandbox_D01CXZR5g7rLQNCXjwewiH", "merchant_id": "70c799bd-db73-41c3-96af-62b367359b7e" }' ``` {% endtab %} {% tab title="Sample Response - Success" %} ```json { "error": false, "data": { "id": "8c0ec61b-aaef-47a9-b107-61a376b36c08", "third_party_name": "braintree", "payengine_token": "card_sandbox_9tNGqlEy8W6eOec18SU5Fh3I", "third_party_token": "hjrpvpex", "third_party_response": { "bin": "424242", "cardType": "Visa", "cardholderName": "John Doe", "commercial": "Unknown", "countryOfIssuance": "Unknown", "createdAt": "2025-03-25T18:11:41Z", "customerId": "43693139716", "customerGlobalId": "Y3VzdG9tZXJfNDM2OTMxMzk3MTY", "customerLocation": "US", "debit": "Unknown", "default": true, "durbinRegulated": "Unknown", "expirationMonth": "11", "expirationYear": "2029", "expired": false, "globalId": "cGF5bWVudG1ldGhvZF9jY19oanJwdnBleA", "graphQLId": "cGF5bWVudG1ldGhvZF9jY19oanJwdnBleA", "healthcare": "Unknown", "imageUrl": "https://assets.braintreegateway.com/payment_method_logo/visa.png?environment=sandbox", "issuingBank": "Unknown", "last4": "4242", "payroll": "Unknown", "prepaid": "Unknown", "prepaidReloadable": "Unknown", "productId": "Unknown", "subscriptions": [], "token": "hjrpvpex", "uniqueNumberIdentifier": "60c0df78f32f782e81a3de1f2d1bfb9a", "updatedAt": "2025-03-25T18:11:41Z", "venmoSdk": false, "verifications": [], "isNetworkTokenized": false, "maskedNumber": "424242******4242", "expirationDate": "11/2029" } }, "errors": null } ``` {% endtab %} {% tab title="Sample Response - Error" %} Sample Error Response when the Platform Token is wrong ```json { "error": false, "message": "Platform token cannot be found" } ``` Sample Error Response when it is failed at the 3rd party processor ```json { "error": true, "data": { "id": "899ba86b-cb5c-4c8a-b19b-8828899fa3fd", "third_party_name": "braintree", "payengine_token": "card_test_D01CXZR5g7rLQNCXmFwCkexY", "third_party_additional_data": {} }, "errors": { /* error details from third-party here */ } } ``` {% endtab %} {% endtabs %} #### NMI {% tabs %} {% tab title="Sample Request" %} **Payload with specific gateway ID** ```bash --header 'Authorization: Basic YOUR_API_KEY' \ --header 'Content-Type: application/json' \ --data '{ "payengine_token": "card_sandbox_D01CXZR5g7rLQNCXjwewiH", "gateway_id": "0c49b17e-9a88-411a-9eda-7e54879055af" }' ``` **Payload with merchant ID** If merchant ID is provided, the system will choose the gateway based on the default enabled gateway for the merchant. ```bash --header 'Authorization: Basic YOUR_API_KEY' \ --header 'Content-Type: application/json' \ --data '{ "gateway": "nmi", "payengine_token": "card_sandbox_D01CXZR5g7rLQNCXjwewiH", "merchant_id": "70c799bd-db73-41c3-96af-62b367359b7e" ``` **Payload for passing gateway credentials** Sample payload for passing gateway credentials directly without requiring merchant gateway configuration. ```bash curl --location 'http:///api/token-exchange' \ --header 'Content-Type: application/json' \ --header 'Authorization: Basic PAYENGINE_SECRET_KEY' \ --data '{ "gateway": "nmi", "merchantId": "PAYENGINE_MERCHANT_ID", "payengineToken": "PAYENGINE_CARD_TOKEN", "thirdPartyRequiredData": { "username": "SECURITY_KEY", "password": "PASSWORD" } }' ``` {% endtab %} {% tab title="Sample Response - Success" %} ```json { "error": false, "data": { "id": "f88657f6-eb8e-4006-b5e2-002eaa0cbb64", "third_party_name": "nmi", // deprecated "gateway": "nmi", "payengine_token": "card_sandbox_hzGbFLSKPZ4ff9yP5vQO8Xoe", "third_party_token": "sZbAzdytjpFXkynKZVKyBSSZgHvaCS1UiVvt", "third_party_response": { "response": "1", "responsetext": "Customer Added", "authcode": "", "transactionid": "", "avsresponse": "", "cvvresponse": "", "orderid": "", "type": "", "response_code": "100", "customer_vault_id": "sZbAzdytjpFXkynKZVKyBSSZgHvaCS1UiVvt" } }, "errors": null } ``` {% endtab %} {% tab title="Sample Response - Error" %} Sample Error Response when the Platform Token is wrong ```json { "error": false, "message": "Platform token cannot be found" } ``` Sample Error Response when it is failed at the 3rd party processor ```json { "error": true, "data": { "id": "899ba86b-cb5c-4c8a-b19b-8828899fa3fd", "third_party_name": "nmi", // deprecated "gateway": "nmi", "payengine_token": "card_test_D01CXZR5g7rLQNCXmFwCkexY", "third_party_additional_data": {} }, "errors": { /* error details from third-party here */ } } ``` {% endtab %} {% endtabs %}