Overview

With Nuvei REST API 2.0, merchants can use these endpoints to create a buyer; update buyer details; retrieve buyer details; 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"
  }
}

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"
  }
}