Skip to main content

Network Tokens

Coming Soon​

Network Tokens allow the creation of a token representing a customer's card details and offer additional benefits over platform tokens, such as:

  • automatic account updater for expired and reissued cards on file
  • token portability between payment providers with no conversion required
  • improved authorization approval rates, and
  • reduced interchange cost on certain transaction categories.

Network tokens is a specific feature which needs to be enabled on your account.

Once the feature has been enabled for your account, all card payment methods created will default to a tokenType of "network", though you will also be able to choose to generate a platform token by explicitly passing tokenType: "platform" in the request payload.

Create Network Tokens​

Network tokens are created by sending request to the POST /payment-method endpoint.

Note that a customer's email address is mandatory, so please include the billingAddress.email attribute.

Clients should submit a JSON request as follows:

Request: Create Network Token
POST /payment-method
{
  "type": "card",
  "card": {
    "expiry": {
      "month": 9,
      "year": 2024
    },
    "number": "4111111111111111",
    "cvc": "123",
    "cvcIndicator": "not-present",
    "tokenType": "network"
  },
  "billingDetails": {
    "address": {
      "line1": "7272 E Indian School Rd",
      "city": "Scottsdale",
      "state": "AZ",
      "postalCode": "85251",
      "country": "USA"
    },
    "name": "John Doe",
    "email": "[email protected]",
    "phone": "5551234567"
  }
}
Response: Create Network Token
{
  "type": "card",
  "token": "054f3ce9-ad96-4306-abcc-5722e5313a71",
  "updatedAt": "2023-07-11T22:44:23.507Z",
  "createdAt": "2023-05-18T00:33:35.958Z",
  "billingDetails": {
    "email": "[email protected]",
    "name": "John Doe",
    "phone": "5551234567",
    "address": {
      "city": "Scottsdale",
      "country": "USA",
      "line1": "7272 E Indian School Rd",
      "postalCode": "85251",
      "state": "AZ"
    }
  },
  "card": {
    "brand": "visa",
    "lastFour": "1111",
    "checks": {
      "cvcCheck": "full-match",
      "addressCheck": "not-verified"
    },
    "expiry": {
      "month": 9,
      "year": 2024
    },
    "tokenType": "network"
  }
}

Network Token Updates​

Network tokens may be updated by the issuer of the underlying card. Tokens may be updated for various reasons, but the most common will be because the expiry date changes, or the issuer suspends or deletes the token.

If you have a webhook subscribed to the payment-method.update event, you will receive a notification when one of your payment methods is updated.

You will then be able to lookup the relevant payment method through the API to get the latest details. If the token is not in an active state, a status attribute will be present in the response payload, containing a code indicating the current state, plus a reason for the state change (if one was supplied by the issuer).

Suspended Network Token Example
{
  "type": "card",
  "token": "054f3ce9-ad96-4306-abcc-5722e5313a71",
  ...
  "status": {
    "code": "SUSPENDED",
    "reason": "SUSPENDED_DUE_TO_FRAUD"
  }
}

Please note the following:

  • if the token is not active, it cannot be used for any payments.
  • if the token is marked as SUSPENDED, there is a possibility that it could be re-activated later once the issuer resolves the reason for suspension.
  • if the token is marked as DELETED, then that token will never become active again and you may need to ask your customer for an alternative payment method.