Token Exchange

The Token Exchange API allows you to obtain a token from a third-party payment processor by providing a Platform Token.

Exchange tokens

Request

POST https://<Platform-host>/api/token-exchange

Body Parameters

Name	Type	Description
gateway_id	UUID	Platform gateway ID if required. Not required if gateway type is provided.
payengine_token *	string	Card token generated by Platform.
merchant_id	UUID	Platform merchant ID if required.
third_party_name (deprecated)	string	Deprecated. Use gateway property instead.
gateway	string	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. List Available Gateways
third_party_required_data	object	Required data (if any) like authentication details for the 3rd party processor.
third_party_additional_data	object	Any 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.
metadata	object	Set 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

Response Object

Card Token Field Definitions

Field Name	Type	Description
data.id	string	Unique identified for the card object.
data.third_party_name (deprecated)	string	Deprecated. Use gateway instead.
data.gateway	string	Name of the 3rd party processor, provided in the request. Example: nmi | sierra | viaconex | stripe | elavon | payrix | etc. List Available Gateways
data.payengine_token	string	Card token generated by Platform provided in the request.
data.third_party_token	string	Card token generated by the 3rd party processor for the information provided in the Platform token.
data.third_party_additional_data	object	Return the third_party_additional_data from the request.
data.third_party_response	object	Contains the exact response from the third party processor.
metadata	object	Return the metadata object provided in the request.
error	boolean	true | false. True when there is an error
errors	object	Return the error response from the third party processor.

Sample Request and Response

Sample Request

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"
         },
}'

Sample Response - Success

{
    "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",
        }
    }

Sample Response - Error

Sample Error Response when the Platform Token is wrong

{
    "error": false,
    "message": "Platform token cannot be found"
}

Sample Error Response when it is failed at the 3rd party processor

{
    "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"
    }
}

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

Sample Request

Payload with specific gateway ID

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

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

Sample Response - Success

{
    "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",
        }
    }

Sample Response - Error

Sample Error Response when the Platform Token is wrong

{
    "error": false,
    "message": "Platform token cannot be found"
}

Sample Error Response when it is failed at the 3rd party processor

{
    "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"
    }
}

Braintree

Sample Request

Payload with specific gateway ID

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

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

Sample Response - Success

{
    "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
}

Sample Response - Error

Sample Error Response when the Platform Token is wrong

{
    "error": false,
    "message": "Platform token cannot be found"
}

Sample Error Response when it is failed at the 3rd party processor

{
    "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 */
    }
}

NMI

Sample Request

Payload with specific gateway ID

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

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

curl --location 'http://<Platform_Host>/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"
    }
}'

Sample Response - Success

{
    "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
}

Sample Response - Error

Sample Error Response when the Platform Token is wrong

{
    "error": false,
    "message": "Platform token cannot be found"
}

Sample Error Response when it is failed at the 3rd party processor

{
    "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 */
    }
}