Nuvei provides advanced server-side APIs for creating and managing payment tokens and buyers.
Payment Tokens
A merchant can tokenize a payment method without doing a payment transaction using a POST /paymentTokens
endpoint. This endpoint is used to tokenize a payment method for subsequent transactions. The same payment method can be tokenized a few times.
Using this endpoint, you can create:
- A payment token
- A payment token linked to a buyer
Example /paymentTokens
Request
{ "processingEntityId": "<your processingEntityId>", "merchantReference": "<the token name in your system>", "paymentOption": { "card": { "cardHolderName": "John Smith", "cardNumber": "5101081046006034", "expirationMonth": "10", "expirationYear": "2026", "cvv": "591" } }, "buyerId": "<unique customer identifier in your system>", "usageIntent": "recurring", "custom": { "hello": "world" } }
Example /paymentTokens
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" } } }, "result": { "status": "success" } }
GET /paymentTokens/{paymentTokenId}
– This endpoint is used to retrieve details of a specific payment token.
Example GET /paymentTokens/{paymentTokenId}
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" } }
PATCH /paymentTokens/{paymentTokenId}
– This endpoint is used for updating payment token details.
You can update the following details for cards:
- Card holder name
- Expiration month
- Expiration year
Example PATCH /paymentTokens/{paymentTokenId}
Request
{ "processingEntityId": "<Your processingEntityId>", "paymentOption": { "card": { "cardHolderName": "John Smint", "expirationMonth": "10", "expirationYear": "2026" } }, "usageIntent": "addCard", "buyerId": "buyer@wherever.com", "merchantReference": "MREF_6f06168d-ff6e-448b-8401-30051eb6b1af" }
Example PATCH /paymentTokens/{paymentTokenId}
Response
{ "result": { "status": "success" } }
DELETE /paymentTokens/{paymentTokenId}
– This endpoint is used for deleting payment tokens. After deletion, the token cannot be used.
Example DELETE /paymentTokens/{paymentTokenId}
Response
{ "result": { "status": "success" } }
Buyers
The following API endpoints are used for creating buyers, updating buyer details, retrieving buyer details, and deleting buyers.
PUT /buyers/{buyerId}
– This endpoint is used to register buyer details for subsequent transactions. If the buyer is already registered in the system, their record is overridden. The buyerId
is the unique identifier of the consumer in your system.
Example Request
{ "processingEntityId": "<your processingEntityId>", "buyerDetails": { "firstName": "John", "lastName": "Smith", "companyName": "Nuvei Corp", "locale": "en-US", "dateOfBirth": "1978-06-27", "email": "john.smith@email.com", "phone": "6175551414", "nationalIdentificationNumber": "221685479", "billingAddress": { "address": "22 Main Street", "addressLine2": "Billing Address Line 2", "addressLine3": "Billing Address Line 3", "zip": "02460", "city": "Boston", "state": "MA", "countryCode": "US", "phone": "6175551414", "addressMatch": "true" }, "shippingAddress": { "sameAsBilling": "true", "address": "22 Main Street", "addressLine2": "Shipping Address Line 2", "addressLine3": "Shipping Address Line 3", "zip": "02460", "city": "Boston", "state": "MA", "countryCode": "US", "firstName": "John", "lastName": "Smith", "phone": "6175551414" } } }
Example Response
{ "result": { "status": "success" } }
GET /buyers/{buyerId}
– This endpoint is used for retrieving buyer details.
Example Response
{ "buyers": [ "buyerId": "<unique customer identifier in your system>", "buyerDetails": { "firstName": "John", "lastName": "Smith", "companyName": "Nuvei Corp", "locale": "en-US", "dateOfBirth": "1978-06-27", "email": "john.smith@email.com", "phone": "6175551414", "workPhone": "6175552222", "nationalIdentificationNumber": "221685479", "billingAddress": { "address": "22 Main Street", "addressLine2": "Billing Address Line 2", "addressLine3": "Billing Address Line 3", "zip": "02460", "city": "Boston", "state": "MA", "countryCode": "US", "phone": "6175551414", "addressMatch": false }, "shippingAddress": { "sameAsBilling": false, "address": "22 Main Street", "addressLine2": "Shipping Address Line 2", "addressLine3": "Shipping Address Line 3", "zip": "02460", "city": "Boston", "state": "MA", "countryCode": "US", "firstName": "John", "lastName": "Smith", "phone": "6175551414" } } } ], "result": { "status": "success" } }
DELETE /buyers/{buyerId}
– This endpoint is used for deleting buyers from the system.
Example Response
{ "result": { "status": "success" } }
GET /buyers/{buyerId}/paymentTokens
– This endpoint is used for retrieving details of a buyer’s payment tokens.
Example Response
{ "paymentTokens": [ { "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" } }
GET /buyers/{buyerId}/paymentTokens/{paymentTokenId}
– This endpoint is used for retrieving details of a buyer’s payment tokens.
Example Response
{ "paymentTokens": { "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" } }