Follow these steps to perform a payment using Nuvei REST API integration:

1. Generate a sessionToken

Press here for details.

2. Send a /payment Request

Perform the payment by sending a /payment request with its mandatory parameters including:

• userTokenId
• amount
• currency
• paymentOption.alternativePaymentMethod class containing:
  • paymentMethod: “apmgw_VIP_Preferred_SDK“
• deviceDetails class containing: ipAddress
• billingAddress class containing: firstName, lastName, country, email
• userDetails class containing:
  

  Parameter	Type	Description
  firstName	String(30)	Customer’s first name.
  lastName	String(40)	Customer’s last name.
  address	String(60)	Customer’s address.
  phone	String(18)	Customer’s phone1.
  city	String(30)	Customer’s city.
  state	String(20)	Customer’s Country Subdivision Codes.
  zip	String(10)	Customer’s ZIP code.
  country	String(20)	US
  dateOfBirth	String(10)	The date of birth of the registering user. (YYYY-MM-DD)
  email	String(100)	Customer’s email address.
  identification	String (9)	Customer's social security number.
  identificationType	String (2)	SS

Example /payment Request

{
  "sessionToken": "<sessionToken from /getSessionToken>",
  "merchantId": "<your merchantId>",
  "merchantSiteId": "<your merchantSiteId>",
  "clientRequestId": "<unique request ID in merchant system>",
  "amount": "200",
  "currency": "USD",
  "userTokenId": "<unique customer identifier in merchant system>",
  "clientUniqueId": "<unique transaction ID in merchant system>",
  "paymentOption": {
    "alternativePaymentMethod": {
      "paymentMethod": "apmgw_VIP_Preferred_SDK"
    }
  },
  "deviceDetails": {
    "ipAddress": "<customer's IP address>"
  },
  "billingAddress": {
    "firstName": "John",
    "lastName": "Smith",
    "country": "US",
    "email": "[email protected]"
  },
  "userDetails": {
    "firstName": "John",
    "lastName": "Smith",
    "address": "22 Main Street",
    "phone": "6175551414",
    "zip": "02460",
    "city": "Boston",
    "country": "US",
    "state": "MA",
    "email": "[email protected]",
    "county": "Suffolk",
    "language": "en",
    "dateOfBirth": "2000-06-30",
    "identification": "123456789",
    "identificationType": "SS"
  },
  "timeStamp": "<YYYYMMDDHHmmss>",
  "checksum": "<calculated checksum>"
}

The response generates and returns a redirect URL (redirectUrl) to redirect the customer to the payment page, as well as a UPO (userPaymentOptionId) for use in future transactions.

Example /payment Response

{
  "internalRequestId": 41462211,
  "status": "SUCCESS",
  "errCode": 0,
  "reason": "",
  "merchantId": "1102398682906145682",
  "merchantSiteId": "228311",
  "version": "1.0",
  "sessionToken": "05dfac30-ca93-4666-9fc7-7cbf711323b5",
  "orderId": "43181761",
  "userTokenId": "VIPPPR1",
  "paymentOption": {
    "redirectUrl": "https://cert.api-gaming.paviliononline.io/gaming/mobility/sdk?mode=deposit&redirectUrl=https%3A%2F%2Fjumpbox.safecharge.com%2Fdmz%2FApmConnectorNotify%2F649%2F665#c0ab9564-be6e-41d2-a164-aef9a917cc30",
    "userPaymentOptionId": "2153237021",
    "card": {}
  },
  "transactionStatus": "REDIRECT"
}

After the transaction is processed, Nuvei sends a Direct Merchant Notification (DMN) that includes the result of the transaction to urlDetails.notificationUrl, which Nuvei recommends including in the /payment request.

1. The merchant collects all of the required transaction input parameters and the following required customer details:
   

   Parameter	Type	Description
   first_name	String(30)	Customer’s first name.
   last_name	String(40)	Customer’s last name.
   address1	String(60)	Customer’s address.
   phone1	String(18)	Customer’s phone1.
   city	String(30)	Customer’s city.
   state	String(20)	Customer’s Country Subdivision Codes.
   zip	String(10)	Customer’s ZIP code.
   country	String(20)	US
   dateOfBirth	String(10)	The date of birth of the registering user. (YYYY-MM-DD)
   email	String(100)	Customer’s email address.
   identification	String (9)	Customer's social security number.
   identificationType	String (2)	SS

   
   For the Social Security Number (SSN), the merchant needs to collect the last four digits of the SSN and use a KYC tool for the remaining SSN data.
2. The merchant prepares the authentication request.
3. The merchant submits an HTTPS request to the Nuvei Payment Page.
4. The user is redirected to the VIP Preferred SDK page. For information about the possible VIP Preferred SDK page user experiences, see below.
5. After the user completes the process on the VIP Preferred SDK page, the user is redirected to the Nuvei Payment Page.

Example Payment Page Request

https://apmtest.gate2shop.com/ppp/purchase.do?checksum=44cc544c46581713fc6307e4840f3b3b&item_open_amount_1=true&customField5=&country=US&personalId=871144552&customField1=meccabingo.com&customField2=a2db82db-8186-44bb-a6d9-cb9f8f7ea25e&mobileNumber=13126122254&identificationType=SS&item_name_1=test_name_1&userid=ScMigrationTest3&isNative=&building=BV%208&ssn=260648678&phone1=13126122254&identification=260648678&pm_hints=&promoBox=&state=GA&payment_method=&zip=30328&customField15=rnk_pr01&appReturnLink=&customSiteName=&merchant_site_id=228311&item_min_amount_1=1&encoding=utf-8&languageCode=DE&version=4.0.0&user_token_id=brandnewtoken12&docUploadSuccessUrl=https%3A%2f%2fwww.safecharge.com%2fpayment-methods&kyc=&total_amount=10&parent_url=%2a&showMessageKeys=false&item_quantity_1=1&item_amount_1=10&merchantLocale=en_US&merchant_unique_id=97c10831-d399-48d7-8ea5-41f89619d2fa6&gender=Male&city=Atlanta&nativeAppFlow=&quick_deposit=&theme_id=&kycFlow=&merchant_id=1102398682906145682&title=Mr&docUploadCancelUrl=https%3A%2f%2fwww.safecharge.com%2fpayments-engine&item_max_amount_1=49&currency=USD&user_token=auto&first_name=John&email=john.doe%40gmail.com&bankCode=3030&firstDepositConfirmation=&time_stamp=2024-06-26.10%3A43%3A11&mobileCountryCode=054&address2=2992&address1=Test%20Address&last_name=Doe&dateOfBirth=1985-01-01&eKYCType=&accountNumber=2116828028&userName=Test%20Username&notify_url=https%3A%2f%2fsrv-bsf-devppptrunk.gw-4u.com%2fppptest%2fNotifyMerchantTest&openInExternalBrowser=

After the transaction is processed, Nuvei sends a Direct Merchant Notification (DMN) that includes the result of the transaction to notify_url, which Nuvei recommends including in the request.

Follow these steps to perform a payout using Nuvei REST API integration:

1. Register a userTokenId

A userTokenId is a field in the Nuvei system containing the user’s identifier in the merchant system.

If you do not have a userTokenId registered in the Nuvei system for this user, then register one by sending a /createUser request, including email, countryCode, firstName, and lastName.

Example /createUser Request

{
  "merchantId":"<your merchantId>",
  "merchantSiteId":"<your merchantSiteId>",
  "clientRequestId":"<unique request ID in merchant system>",
  "userTokenId":"<unique user identifier in merchant system>",
  "email":"[email protected]",
  "countryCode":"US",
  "firstName":"John",
  "lastName":"Smith",
  "timeStamp":"<YYYYMMDDHHmmss>",
  "checksum":"<calculated checksum>"
}

Example /createUser Response

{
  "userId":78403498,
  "internalRequestId":552360538,
  "status":"SUCCESS",
  "errCode":0,
  "reason":"",
  "merchantId":"2439523627382132721",
  "merchantSiteId":"224428",
  "version":"1.0",
  "clientRequestId":"20221108130736"
}

The request registers the userTokenId in the Nuvei system, which is needed to generate a UPO in the next step.

2. Create the UPO

Create a UPO by sending an /addUPOAPM request and include:

• userTokenId – Unique customer identifier in the merchant’s system.
• paymentMethodName: “apmgw_VIP_Preferred_SDK“

Example /addUPOAPM Request

{
  "merchantSiteId": "<your merchantSiteId>",
  "merchantId": "<your merchantId>",
  "userTokenId": "<unique customer identifier in merchant system>",
  "clientRequestId": "<unique request ID in merchant system>",
  "timeStamp": "<YYYYMMDDHHmmss>",
  "paymentMethodName": "apmgw_VIP_Preferred_SDK",
  "checksum": "<calculated checksum>"
}

The request returns an encrypted userPaymentOptionId (UPO) representing the user’s APM account details.

Example /addUPOAPM Response

{
  "internalRequestId": 34302991,
  "status": "SUCCESS",
  "errCode": 0,
  "reason": "",
  "merchantId": "4972436454212160565",
  "merchantSiteId": "209631",
  "version": "1.0",
  "clientRequestId": "20231016153027",
  "userPaymentOptionId": 2153048311
}

3. Send a /payout Request

Send a /payout request that includes the userPaymentOptionId, which contains the user’s previously stored APM account details, and its mandatory parameters, including:

• userDetails class containing:
  

  Parameter	Type	Description
  firstName	String(30)	Customer’s first name.
  lastName	String(40)	Customer’s last name.
  address	String(60)	Customer’s address.
  phone	String(18)	Customer’s phone1.
  city	String(30)	Customer’s city.
  state	String(20)	Customer’s Country Subdivision Codes.
  zip	String(10)	Customer’s ZIP code.
  country	String(20)	US
  dateOfBirth	String(10)	The date of birth of the registering user. (YYYY-MM-DD)
  email	String(100)	Customer’s email address.
  identification	String (9)	Customer's social security number.
  identificationType	String (2)	SS

After the transaction is processed, Nuvei sends a Direct Merchant Notification (DMN) that includes the result of the transaction to urlDetails.notificationUrl, which Nuvei recommends including in the /payout request.

Example Payment Page Request

https://apmtest.gate2shop.com/ppp/withdrawal/withdraw.do?checksum=fa6154691dc982a709239c581b8e6ee4&customField5=&country=US&customField1=meccabingo.com&mobileNumber=13126122255&customField3=333&identificationType=SS&userid=UID&building=BV%208&isNative=&phone1=13126122255&wd_open_amount=true&identification=431528639&state=GA&zip=30328&suggestedAmount3=&customSiteName=&appReturnLink=&merchant_site_id=228311&encoding=utf8&languageCode=DE&version=4.0.0&user_token_id=BRNEWTOKEN123&suggestedAmount2=&suggestedAmount1=&kyc=&parent_url=%2a&merchantLocale=en_US&merchant_unique_id=merchant_unique_id&gender=Male&city=Atlanta&backUrl=&theme_id=&kycFlow=&merchant_id=1102398682906145682&title=Mr&showCancelButton=1&wd_max_amount=50&user_token=auto&first_name=Galina&email=john.doe%40gmail.com&time_stamp=2024-06-26.10%3A53%3A15&mobileCountryCode=054&address2=15&wd_amount=10&address1=Test%20Address&last_name=Decheva&dateOfBirth=1985-01-01&eKYCType=&userName=Test%20Username&SSN=431528639&layout=2&wd_currency=USD&wd_min_amount=10