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.
Upon a successful payment transaction, 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, retrieve and update token details, and delete tokens.
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
block 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
block 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
block 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
block:
-
name
: “ACH“data
block 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
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" } }
Deleting a Payment Token
To update the details of an existing payment token, the merchant can send a DELETE request to /payment-tokens/{payment-token-id}
. After deleting a token, it can no longer be used.
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" } } }