Token Exchange

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

Exchange tokens

Request

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

Body Parameters

Name

Type

Description

gateway_id

UUID

PayEngine gateway ID if required. Not required if gateway type is provided.

payengine_token *

string

Card token generated by PayEngine.

merchant_id

UUID

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

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

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:

data.payengine_token

string

Card token generated by PayEngine provided in the request.

data.third_party_token

string

Card token generated by the 3rd party processor for the information provided in the PayEngine 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

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

{
    "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 Error Response when the PayEngine Token is wrong

{
    "error": false,
    "message": "PayEngine 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 PayEngine gateway ID or merchant ID in the token exchange request in order to map the entities in the third-party to the merchant.

Payrix

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

{
    "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 Error Response when the PayEngine Token is wrong

{
    "error": false,
    "message": "PayEngine 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

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

{
    "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 Error Response when the PayEngine Token is wrong

{
    "error": false,
    "message": "PayEngine 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

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

{
    "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 Error Response when the PayEngine Token is wrong

{
    "error": false,
    "message": "PayEngine 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 */
    }
}

PreviousGet Card Account Updater Summary NextACH Tokens

Last updated 27 days ago