Payment Tokens

Home    Online Payments    REST 2.0 (Beta Version)    Features    Payment Tokens

On this page:

Overview

With Nuvei REST API 2.0, when a customer makes a payment for the first time, in the /payments request, the merchant provides:

  • Payment method details – For example, credit card details or details for an alternative payment method (APM).
  • buyerId – Unique identifier for the consumer in the merchant’s system.

By default, Nuvei automatically stores this information, creates a payment token to represent it, and provides the paymentTokenId in the response. The next time a customer wants to use the payment method for a transaction, the merchant does not need to collect the payment method details again. Instead, the merchant includes buyerId and paymentTokenId in the request. For information about how to use payment tokens in payments, see below.

Nuvei also provides the REST 2.0 endpoints listed below to create payment tokens, and to retrieve and update token details.

REST 2.0 does not support Nuvei payment tokens for Apple Pay and Google Pay. When submitting /payments requests, the merchant provides the token it received from Apple Pay or Google Pay.


Creating a Payment Token

To tokenize a payment method without performing a payment, send a POST /payment-tokens request with its mandatory parameters, which depend on the payment method (card or APM). The response includes the paymentTokenId to use in subsequent transaction requests. The same payment method can be tokenized more than once.

Using this endpoint, the merchant can create:

  • A payment token
  • A payment token linked to a buyer

Creating a Payment Token for a Card

Include the paymentOption.card class with its mandatory parameters:

  • cardNumber
  • expirationMonth
  • expirationYear
Example /payment-tokens Request for a Card
{
  "processingEntityId": "<your processingEntityId>",
  "merchantReference": "<token name in your system>",
  "paymentOption": {
    "card": {
      "cardHolderName": "John Smith",
      "cardNumber": "4000027891380961",
      "expirationMonth": "12",
      "expirationYear": "2030",
      "cvv": "591"
    }
  },
  "buyerId": "<unique customer identifier in merchant system>"
  "custom": {
    "hello": "world"
  }
}
Example /payment-tokens Response for a Card
{
  "paymentToken": {
    "paymentTokenId": "1eaf1356-a9a2-4a16-a0c1-290ba2265257",
    "cccId": 1,
    "paymentOption": {
      "card": {
        "cardHolderName": "John Smith",
        "maskedCardNumber": "4***0961",
        "bin": "546221",
        "expirationMonth": "12",
        "expirationYear": "2030",
        "cardType": "Credit",
        "cardBrand": "MASTERCARD",
        "cardProduct": "",
        "cardProgram": "",
        "cardProductType": "",
        "isPrepaid": "true",
        "issuingCountry": "US",
        "isVirtual": "true",
        "isDynamicCurrencyConversionSupported": "true"
      }
    }
  },
  "result": {
    "status": "success"
  }
}

Creating a Payment Token for an APM

Send a POST /payment-tokens request with its mandatory parameters and including:

  • buyerId – The unique customer identifier in the merchant system.
  • paymentOption.alternativePaymentMethod class containing:
    • name: “<APM name>” – The name of the APM in the Nuvei system, which can be different than the plain-text name of the APM.
    • data class containing APM-specific mandatory input fields.
Example /payment-tokens Request for an APM

For example, to create a payment token for the Bank Transfer (ACH) APM, include in the paymentOption.alternativePaymentMethod class:

    • name: “ACH“
    • data class containing:
      • accountNumber: “<customer’s bank account number>“
      • routingNumber: “<bank’s nine-digit ACH routing number, including leading zeros>“
Example /payment-tokens Request
{
  "processingEntityId": "<your processingEntityId>",
  "merchantReference": "<token name in your system>",
  "paymentOption": {
    "alternativePaymentMethod": {
      "name": "ACH",
      "data": {
        "accountNumber": "111111111",
        "routingNumber": "999999992"
      }
    }
  },
  "buyerId": "<unique customer identifier in your system>",
  "custom": {
    "hello": "world"
  }
}
Example /payment-tokens Response for an APM
{
  "paymentToken": {
    "paymentTokenId": "1eaf1356-a9a2-4a16-a0c1-290ba2265257",
    "alternativePaymentMethod": {
      "name": "ACH",
      "data": {
        "accountNumber": "111111111",
        "routingNumber": "999999992"
      }
    },
    "result": {
      "status": "success"
    }
  }
}

Retrieving Token Details

To retrieve the details of an existing payment token, the merchant can send a GET request to /payment-tokens/{payment-token-id}.

Example /payment-tokens/{payment-token-id} Response
{
  "paymentToken": {
    "paymentTokenId": "1eaf1356-a9a2-4a16-a0c1-290ba2265257",
    "cccId": 1,
    "paymentOption": {
      "card": {
        "cardHolderName": "John Smith",
        "maskedCardNumber": "5***6034",
        "bin": "546221",
        "expirationMonth": "10",
        "expirationYear": "2026",
        "cardType": "Credit",
        "cardBrand": "MASTERCARD",
        "cardProduct": "",
        "cardProgram": "",
        "cardProductType": "",
        "isPrepaid": "true",
        "issuingCountry": "US",
        "isVirtual": "true",
        "isDynamicCurrencyConversionSupported": "true"
      }
    },
    "buyerId": "<unique customer identifier in your system>",
    "merchantReference": "MREF_6f06168d-ff6e-448b-8401-30051eb6b1af",
    "processingEntityId": "80aef199-b89a-4d59-ba0c-f2cd3c25d5cd",
    "usageIntent": "recurring"
  },
  "result": {
    "status": "success"

  }
}

Merchants can also retrieve the details of an existing payment token by sending a GET request to /buyers/{buyer-id}/payment-tokens/{payment-token-id}. For more information, see Retrieving Details for a Single Payment Token on the Buyer Management page.

Updating Payment Token Details

To update the details of an existing payment token, the merchant can send a PATCH request to /payment-tokens/{payment-token-id}.

For card payment methods, the merchant can update:

  • Cardholder name
  • Expiration month
  • Expiration year

The merchant can use this endpoint to link a payment token to a buyer.

Example /payment-tokens/{payment-token-id} Request
{
  "processingEntityId": "<your processingEntityId>",
  "paymentOption": {
    "card": {
      "cardHolderName": "John Smith",
      "expirationMonth": "10",
      "expirationYear": "2026"
    }
  },
  "usageIntent": "addCard",
  "buyerId": "<unique customer identifier in merchant system>",
  "merchantReference": "MREF_6f06168d-ff6e-448b-8401-30051eb6b1af"
}
Example /payment-tokens/{payment-token-id} Response
{
  "result": {
    "status": "success"
  }
}

Using Payment Tokens in Payments

Merchants can use payment tokens in a variety of REST 2.0 transaction requests, as described throughout the REST 2.0 documentation. Those transactions fall into two general categories:

  • Customer-initiated transactions (CITs) – Merchants can present a list of the customer’s existing payment methods (payment tokens) in a gallery on the payment page. The customer’s checkout experience is improved because they simply select a previous payment method (payment token) instead of providing payment method details again. Then, the merchant sends the encrypted paymentTokenId for the payment token (payment method) selected by the customer in a /payments request.
  • Merchant-initiated transactions (MITs) – Transactions initiated by the merchant with the customer’s prior consent.
Example CIT /payments Request with paymentTokenId
{
  "processingEntityId": "<your processingEntityId>",
  "amount": 10.5,
  "currency": "USD",
  "transactionType": "Sale",
  "paymentOption": {
    "paymentToken": {
      "paymentTokenId": "<ID of a previously stored payment method>"
    }
  },
  "custom": {
    "description": "Some description"
  },
  "deviceDetails": {
    "browser": {
      "acceptHeader": "Y",
      "userAgent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/105.0.0.0 Safari/537.36",
      "javaEnabled": "true",
      "language": "en-US",
      "colorDepth": "24",
      "screenHeight": "1080",
      "screenWidth": "1920",
      "timeZone": "0",
      "javaScriptEnabled": "true"
    }
  },
  "buyerDetails": {
    "buyerId": "unique customer identifier in your system",
    "firstName": "John",
    "lastName": "Smith",
    "companyName": "Nuvei Corp",
    "dateOfBirth": "1978-01-01",
    "email": "[email protected]",
    "phone": "6175551414",
    "billingAddress": {
      "address": "22 Main Street",
      "zip": "02460",
      "city": "Boston",
      "countryCode": "US",
      "phone": "6175551414",
      "addressMatch": "true"
    },
    "shippingAddress": {
      "sameAsBilling": "true",
      "address": "22 Main Street",
      "zip": "02460",
      "city": "Boston",
      "countryCode": "US",
      "phone": "6175551414"
    }
  }
}
Example CIT /payments Response with paymentTokenId
{
    "paymentId": "375041",
    "transactionId": "2110000000010964462",
    "externalTransactionId": "211010964462",
    "amount": 10.5,
    "currency": "USD",
    "transactionType": "Sale",
    "result": {
        "status": "approved"
    },
    "authCode": "966230",
    "avsCode": "S",
    "partialApproval": {
        "requestedAmount": 10.5,
        "requestedCurrency": "USD"
    },
    "paymentOption": {
        "card": {
            "cardHolderName": "John Smith",
            "maskedCardNumber": "5****6034",
            "bin": "523233",
            "last4Digits": "6034",
            "expirationMonth": "10",
            "expirationYear": "26",
            "acquirerId": "99",
            "cardType": "Credit",
            "cardBrand": "MASTERCARD",
            "paymentTokenId": "b058c947-011d-4695-969a-3d6dae9a1d91"
        }
    }
}
Last update iconLast modified December 2024