Direct Tokenization

Availability

**Use of the production Forward API is subject to eligibility.** Contact your Account Manager for more information or submit an inquiry to our Business Development team.

Direct tokenization utilizes the Forward API to generate a tokenized PAN for a payment instrument.

POST

https://forwarding.sandbox.braintreegateway.com/tsp

Important

You must be pre-approved to use this endpoint. If you are not approved, you will receive an error with a 403 status code when making requests to this endpoint. Keep in mind that the Payment Card Industry (PCI) views TPANs as PANs, which means they should be handled with the same care and compliance as credit card numbers.

Parameters

device_dataString

The device_data parameter contains session identifiers ultimately used for Risk decisions. Provide the full string received from the Braintree client SDK.

merchant_idString

Required

The unique identifier of the merchant whose Vault will be accessed.

payment_method_nonceString

The payment_method_nonce of the payment instrument being tokenized.

payment_method_tokenString

The payment_method_token of the payment instrument being tokenized.

tspobject

Tokenization Service Provider options

currency_codeString

The currency code the max amount should apply to. Currently only enforced for Discover TPANs. Default USD.

expire_atString

If provided, the tokenized PAN may be used any number of times until expire_at, an ISO 8601 date with optional time. This does not set $expiration_month and/or $expiration_year. Currently only enforced for Discover TPANs.

max_amountString

The maximum amount the tokenized PAN can be charged. Currently only enforced for Discover TPANs.

require_cryptogramboolean

If set to true, a cryptogram will be returned instead of a dynamic CVV. Currently only compatible with Visa network tokens. Default false.

device_dataString

The device_data parameter contains session identifiers ultimately used for Risk decisions. Provide the full string received from the Braintree client SDK.

merchant_idString

Required

The unique identifier of the merchant whose Vault will be accessed.

payment_method_nonceString

The payment_method_nonce of the payment instrument being tokenized.

payment_method_tokenString

The payment_method_token of the payment instrument being tokenized.

tspobject

Tokenization Service Provider options

currency_codeString

The currency code the max amount should apply to. Currently only enforced for Discover TPANs. Default USD.

expire_atString

max_amountString

The maximum amount the tokenized PAN can be charged. Currently only enforced for Discover TPANs.

require_cryptogramboolean

If set to true, a cryptogram will be returned instead of a dynamic CVV. Currently only compatible with Visa network tokens. Default false.

Tokenization in the sandbox environment

When calling the TSP (Token Service Provider) in the sandbox environment, test values for number, cvv, expiration_month, and expiration_year will be returned.

Example - Discover TPAN

bash

curl https://forwarding.sandbox.braintreegateway.com/tsp   -H "Content-Type: application/json"   -X POST   -u "${BRAINTREE_PUBLIC_KEY}:${BRAINTREE_PRIVATE_KEY}"   -d '{
    "merchant_id": "'"$BRAINTREE_MERCHANT_ID"'",
    "payment_method_nonce": "fake-valid-nonce"
  }'

# Returns JSON object with cvv, expiration_month, expiration_year and number, eg
# {"expiration_year":"2036","expiration_month":"4","cvv":"939","number":"6011000991300009"}

Example - Visa network token

bash

curl https://forwarding.sandbox.braintreegateway.com/tsp   -H "Content-Type: application/json"   -X POST   -u "${BRAINTREE_PUBLIC_KEY}:${BRAINTREE_PRIVATE_KEY}"   -d '{
    "merchant_id": "'"$BRAINTREE_MERCHANT_ID"'",
    "payment_method_nonce": "fake-valid-visa-nonce",
    "tsp": {"require_cryptogram": true}
  }'

# Returns JSON object with cryptogram, expiration_month, expiration_year, number and network TRID, eg
# {"cryptogram":"AgAAAAAAALm1mmu9TqJGQAAAAAA=",
#  "expiration_year":"2036",
#  "expiration_month":"4",
#  "network_token_requestor_id":"40010036958",
#  "number":"4012000033330521"}