availability

Use of Network Tokenization is subject to eligibility.

Please contact your Account Manager for more information or submit an inquiry to our Business Development team.

Defining tokenization

The term "tokenization" has taken on multiple meanings in the payments domain, so it's worth taking a moment to clarify what we mean by tokenization in the Braintree Forward API.

At a high level, tokenization is the issuance of a short-lived token that represents payment information – often credit card details – that's typically intended to be used for a single transaction. This issuance can happen in either an open-loop or a closed-loop system:

  • Open-loop: Typically uses a short-lived token that looks like a credit card number, generated by a tokenization service provider (TSP). This token allows third parties to create transactions with a customer's payment method without having direct access to the underlying payment information. Apple Pay and Google Pay are well-known examples of open-loop tokenization, also known as network tokenization.
  • Closed-loop: Typically uses a short-lived token that only has significance within the system that generated it. Braintree payment method nonces are an example of closed-loop tokens.

The Braintree Forward API can act as a TSP in an open-loop network.

Supported payment methods

The Forward API supports two kinds of open-loop tokens: Discover TPANs and Visa network tokens.

Discover TPANs are currently restricted to US-issued credit cards, PayPal accounts, and Venmo accounts. Visa network tokens are available for Visa credit and non-prepaid debit cards, world-wide.

In sandbox, tokenization of PayPal accounts requires linking PayPal credentials that have been enabled for tokenization. In production, tokenization requires linked PayPal credentials.

Capabilities

Discover TPAN Visa Network Token
Region restrictions US only World-wide
Supports amount restrictions Yes, via max_amount No
Supports cryptogram-based authorizations No Yes, specify require_cryptogram
Supports CVV-based authorizations Yes, required for authorization unless expire_at is specified No
Supports multiple authorizations Yes, if expire_at is specified No
Supports PayPal Yes, currently only for channel-initiated billing agreements (CIBs) No
Supports TTL restrictions Yes, via expire_at No
Supports Venmo Yes No

Usage

Configs using tokenization are nearly identical to CreditCard configs, with two key differences:

  1. "NetworkTokenizedCard" will be included among the types
  2. $cvv and $cryptogram will be available as variables

Tokenization will be attempted automatically if a config supports the "NetworkTokenizedCard" type but not the payment method type of the specified payment_method_token or payment_method_nonce. If the config supports both, "tokenize_on_forward" parameter can be set to true to send tokenized card information.

You can optionally pass TSP Options when forwarding a specific payment method to a third party to limit what can be done with a Discover TPAN. For example, if you passed max_amount as 10.00, and the third party tried to charge 900.00, the transaction would fail.

Example

bash
curl https://forwarding.sandbox.braintreegateway.com/ \
  -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",
    "debug_transformations": true,
    "tokenize_on_forward": true,
    "url": "https://httpbin.org/post",
    "method": "POST",
    "config": {
      "name": "inline_example_debug",
      "methods": ["POST"],
      "url": "^https://httpbin\\.org/post$",
      "request_format": {"/body": "json"},
      "types": ["NetworkTokenizedCard"],
      "transformations": [{
        "path": "/body/card/number",
        "value": "$number"
      },
      {"path": "/body/card/cvv", "value": "$cvv"}]
    }
  }'

Returns:

JSON
{"cvv:":"123","number":"6011111111111117"}

See also