Overview
With Nuvei REST API 2.0, merchants can use these endpoints to create a buyer; update buyer details; retrieve buyer details; delete a buyer; and retrieve details for all of a buyer’s payment tokens or the details for a single payment token.
Creating a Buyer or Updating a Buyer’s Details
To create a buyer by registering the buyer’s details for subsequent transactions, the merchant can send a PUT request to /buyers/{buyer-id}
. The buyerId
is the unique identifier of the consumer in the merchant’s system. If the buyerId
already exists in the Nuvei system, the information in the PUT request replaces the existing information for that buyerId
.
Example PUT /buyers/{buyer-id}
Request
{ "processingEntityId": "<your processingEntityId>", "buyerDetails": { "firstName": "John", "lastName": "Smith", "companyName": "Nuvei Corp", "locale": "en-US", "dateOfBirth": "1978-06-27", "email": "[email protected]", "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 PUT /buyers/{buyer-id}
Response
{ "result": { "status": "success" } }
Retrieving Buyer Details
To retrieve a buyer’s details, the merchant can send a GET request to /buyers/{buyer-id}
.
Example GET /buyers/{buyer-id}
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": "[email protected]", "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" } }
Deleting a Buyer
To delete a buyer, the merchant can send a DELETE request to /buyers/{buyer-id}
.
Example DELETE /buyers/{buyer-id}
Response
{ "result": { "status": "success" } }
Retrieving a Buyer’s Payment Token Details
To retrieve the details for all of a buyer’s payment tokens, the merchant can send a GET request to /buyers/{buyer-id}/payment-tokens
.
Example /buyers/{buyer-id}/payment-tokens
Response – Single Payment Token for buyerId
{ "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" } }
Retrieving Details for a Single Payment Token
To retrieve details of a single payment token, the merchant can send a GET request to /buyers/{buyer-id}/payment-tokens/{payment-token-id}
.
Example /buyers/{buyer-id}/payment-tokens/{payment-token-id}
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" } }