To perform a payout with Efectivo using the REST API integration method:

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 – countryCode must be MX.

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":"MX",
  "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 UPO 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_PESPay“
• apmData class containing:
  • pes_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_PESPay",
  "apmData": {
       "pes_email": "[email protected]"
  },
  "timeStamp": "<YYYYMMDDHHmmss>",
  "checksum": "<calculated checksum>"
}

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

Example /addUPOAPM Response

{
  "internalRequestId": 1106593228,
  "status": "SUCCESS",
  "errCode": 0,
  "reason": "",
  "merchantId": "979047831696752006",
  "merchantSiteId": "217268",
  "version": "1.0",
  "clientRequestId": "20240611154513",
  "userPaymentOptionId": 116304878
}

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.

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://ppp-test.safecharge.com/ppp/withdrawal/withdraw.do?merchant_id=979047831696752006&merchant_site_id=217268&user_token=auto&merchantLocale=undefined&wd_amount=1.23&wd_currency=MXN&country=MX&wd_min_amount=1&wd_max_amount=100&user_token_id=Test_2036613329&userid=&time_stamp=2024-08-14%2015:27:20&version=4.0.0&layout=0&checksum=3343f4ff459dd4ce7862a88d8b699d3c57c27625e57c01e2b15783d26b670d41&

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.