1. Generate a sessionToken. Press here for details.
2. Send an /accountCapture request that includes the following mandatory fields as shown in the example request below:
   • userTokenId – Unique customer identifier in merchant system.
   • paymentMethod: “apmgw_MX_Payouts“
   • currencyCode: MXN
   • countryCode: MX
     
     

     Example /accountCapture Request

     {
       "sessionToken": "<sessionToken from /getSessionToken>",
       "merchantId": "<your merchantId>",
       "merchantSiteId": "<your merchantSiteId>",
       "userTokenId": "<unique customer identifier in merchant system>",
       "paymentMethod": "apmgw_MX_Payouts",
       "currencyCode": "MXN",
       "countryCode": "MX",
     }

     The request returns a redirectUrl.

     Example /accountCapture Response

     {
       "redirectUrl":"https://ppp-test.safecharge.com/ppp/acs/get.do?cccid=111&country=MX&language=en&amount=100&currency=MXN&ReturnURL=https%3a%2f%2ftest.safecharge.com%2fAPMNotificationGateway%2fSTPmex%2fSTPmexRedirectWithdrawResponse.ashx&APMTransactionID=404EE9CD3BBDDD2622BECE95DA936FF1&AccountInfo5=+",
       "userTokenId":"1810test",
       "sessionToken":"89c762b7-06c6-45f4-8517-0e335350d0e3",
       "internalRequestId":603948068,
       "status":"SUCCESS",
       "errCode":0,
       "reason":"",
       "merchantId":"221195993304907999",
       "merchantSiteId":"232618",
       "version":"1.0"
     }

3. Use redirectUrl to redirect the customer to the APM’s account details capture interface for them to enter their account details.
4. Once the information is captured, Nuvei stores the data in a userPaymentOptionId (UPO) identifier, and sends a with the newly created userPaymentOptionId to urlDetails.notificationUrl, which Nuvei recommends including in the /accountCapture request.
5. Send a /payout request and include the userPaymentOptionId, which contains the user’s previously stored APM account details. Press here for an example.

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":"<2-letter ISO country code>",
  "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 (userId) in the Nuvei system, which is needed to generate a userPaymentOptionId in the next step.

2. Create the UPO

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

• userTokenId – The unique user identifier in your system.
• paymentMethodName: “apmgw_MX_Payouts“
• apmData class containing:
  • beneficiaryBank – Press here to see list of supported beneficiaryBank codes.
  • beneficiaryName
  • beneficiaryNumber
  • beneficiaryType
• billingAddress class containing: country and email

Example /addUPOAPM Request

{
  "merchantId":"<your merchantId>",
  "merchantSiteId":"<your merchantSiteId>",
  "clientRequestId":"<unique request ID in merchant system>",
  "userTokenId":"<unique customer identifier in merchant system>",
  "paymentMethodName":"apmgw_MX_Payouts",
  "apmData": {
    "beneficiaryBank": "<supported beneficiary bank code>",
    "beneficiaryName": "John Smith",
    "beneficiaryNumber": "<CLABE number>",
    "beneficiaryType": "40"
  },
  "billingAddress":{
    "country":"MX",
    "email":"[email protected]"
  },
  "timeStamp":"<YYYYMMDDHHmmss>",
  "checksum":"<calculated checksum>"
}

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

Example /addUPOAPM Response

{
  "userPaymentOptionId":83458468,
  "internalRequestId":553078068,
  "status":"SUCCESS",
  "errCode":0,
  "reason":"",
  "merchantId":"2439523627382132721",
  "merchantSiteId":"224428",
  "version":"1.0",
  "clientRequestId":"20221109154215"
}

3. Send a /payout Request

Send a /payout request and include the userPaymentOptionId, which contains the user’s previously stored APM account details. Press here for an example.

The following flow describes how to capture a user’s account details before processing a payout request using Nuvei Web SDK integration.

1. Initiate a Session

Before you can submit payment using the client-side Nuvei Web SDK, you need to send the /openOrder API call.

2. Initialize the Web SDK

Instantiate the Web SDK with the sessionToken received from the server call to /openOrder.

3. Send an accountCapture() request

a. Send an accountCapture() request that includes the following mandatory fields (as shown in the example request below):

• userTokenId – Unique customer identifier in merchant system.
• paymentMethod: “apmgw_MX_Payouts“
• currencyCode
• countryCode

Example accountCapture() Request

sfc.accountCapture({
  sessionToken: "<sessiontoken>",
  merchantId: "<your merchantId>",
  merchantSiteId: "<your merchantSiteId>",
  paymentMethod: "apmgw_MX_Payouts",
  userTokenId: "<unique customer identifier in merchant system>",
  currencyCode: "MXN",
  countryCode: "MX",
  languageCode: "en",
  urlDetails:{
    successUrl:"<URL the customer is directed to after a successful transaction>",
    pendingUrl:"<URL the customer is directed to when the transaction response is pending>",
    failureUrl:"<URL the customer is directed to after an unsuccessful transaction>",
    notificationUrl:"<URL to which DMNs are sent>"
  },
sourceApplication: "WebSDK"
}, function(accountRes) {
    console.log(accountRes);
})

The request returns a redirectUrl.

Example accountCapture() Response

{
    "redirectUrl": "<redirect URL to enter account details>",
    "userTokenId": "bankCaptureUser4",
    "sessionToken": "e44a932a-e9fc-4482-a570-cf07175408e0",
    "internalRequestId": 23238261,
    "status": "SUCCESS",
    "errCode": 0,
    "reason": "",
    "merchantId": "8256777005602846935",
    "merchantSiteId": "112106",
    "version": "1.0"
}

b. Use the redirectUrl to redirect the customer to the APM’s account details interface, to enter their account details.

c. Once the information is captured, Nuvei stores the data in a UPO record, and sends a DMN with the newly created userPaymentOptionId to urlDetails.notificationUrl, which Nuvei recommends including in the /accountCapture request.

4. Send a /payout Request

Send a /payout request and include the userPaymentOptionId, which contains the user’s previously stored APM account details. Press here for an example.

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":"<2-letter ISO country code>",
  "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 (userId) in the Nuvei system, which is needed to generate a userPaymentOptionId in the next step.

2. Create the UPO

Create a UPO by sending an addApmUpo() request and include:

• userTokenId – The unique user identifier in your system.
• paymentMethodName: “apmgw_MX_Payouts“
• apmData class containing:
  • beneficiaryBank – Press here to see list of supported beneficiaryBank codes.
  • beneficiaryName
  • beneficiaryNumber
  • beneficiaryType
• billingAddress class containing: country and email

Example addApmUpo() Request

function addApmUpo() {
  sfc.addApmUpo({
    "paymentMethodName": "apmgw_MX_Payouts",
    "apmData": {
        "beneficiaryBank": "<supported beneficiary bank code>",
        "beneficiaryName": "John Smith",
        "beneficiaryNumber": "<CLABE number>",
        "beneficiaryType": "40"
    },
     billingAddress: { // optional
       email: '[email protected]',
       country: 'MX'
    } },
    function(result) {
      console.log(result);
  })

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

Example addApmUpo() Response

{
    "result": "ADDED",
    "errCode": 0,
    "errorDescription": "",
    "userPaymentOptionId": "14958143",
    "cancelled": false
}

3. Send a /payout Request

Send a /payout request and include the userPaymentOptionId, which contains the user’s previously stored APM account details. Press here for an example.