Follow these steps to perform a payment:

1. Generate a sessionToken

Press here for details.

2. Register a userTokenId

When relevant, it is preferable that a merchant uses the userTokenId generated from a payment transaction that was previously performed. If so, skip to Step 3.

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 an email and countryCode.

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":"<2-letter ISO country code>",
  "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 (userId) in the Nuvei system.

3. Send a /payment Request

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

  • userTokenId
  • amount
  • currency
  • paymentOption.alternativePaymentMethod block containing:
    • paymentMethod: "apmgw_PayCash"
  • deviceDetails block containing: ipAddress
  • billingAddress block containing: country and email
  • userDetails block containing: country
Example /payment Request
{
  "sessionToken":"<sessionToken from /getSessionToken>",
  "merchantId":"<your merchantId>",
  "merchantSiteId":"<your merchantSiteId>",
  "clientRequestId":"<unique request ID in merchant system>",
  "amount":"1000",
  "currency":"MXN",
  "userTokenId":"<unique customer identifier in merchant system>",
  "clientUniqueId":"<unique transaction ID in merchant system>",
  "paymentOption":{
    "alternativePaymentMethod":{
      "paymentMethod":"apmgw_PayCash"
    }
  },
  "deviceDetails":{
    "ipAddress":"<customer's IP address>"
  },
  "billingAddress":{
    "country":"MX",
    "email":"[email protected]"
  },
  "userDetails":{
    "country":"CO"
  },
  "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

TBD

The request is processed and an “APPROVED” (or “DECLINED”) DMN is returned.

Example DMN with Status=PENDING
TBD
Example DMN with Status=APPROVED
TBD
Example DMN with Status=DECLINED
TBD