Attributes

• METHOD TYPEReal-Time Bank Transfer
• PAYMENTS
• PAYOUTS
• REFUNDS
• RECURRING

Introduction

Nuvei Instant Bank Transfer (IBT) is a verified Automated Clearing House (ACH) product that provides access to consumer online bank account information, enabling merchants to verify consumer profile information and ensure accurate bank information before processing payments through the US-based ACH network. Nuvei IBT was previously known as Mazooma.

Supported Countries

• United States

Supported Currencies

• USD

Nuvei IBT ACH Transactions

This is a summary of the general process:

• The first time that you perform a deposit using Nuvei IBT for a customer, you should send a payment (deposit) request with the customer’s details using a Payment (without UPO) request.
• The system returns a redirectUrl, to which you must redirect the customer for them to capture their bank details.
• After capturing the customer input, Nuvei IBT processes the request, as described in the “Payment (Deposit) Flow” section.
• If the deposit is successful, then the Nuvei system generates and return a userPaymentOptionId (UPO), for use in future Nuvei IBT ACH transactions.
  For more details, see the Managing Bank Accounts section.
• Subsequent deposits using Nuvei IBT are performed by sending a Payment (with UPO).
• Withdrawals using Nuvei IBT are performed by sending a Payout (withdrawal) request.

Payment (Deposit) Flow

Nuvei IBT begins processing a “deposit” (payment) request after receiving these inputs:

• The “deposit” (payment) request from you (on behalf of your customer).
• The bank account from which to pay, selected by the customer.

Nuvei IBT processes ACH payment requests (deposits) in the following flow:

1. Nuvei IBT first checks for the availability of the requested amount in the customer’s bank account.
   • If the funds are available:
     Nuvei IBT responds with “APPROVED” and you receive a Direct Merchant Notification (DMN) with “status=APPROVED“.
     IBT – US does not actually perform the transfer at this point. They attempt to perform the transfer in the next step.

   • If the funds are NOT available (or for some other “decline” reason):
     Nuvei IBT responds with “DECLINED” and you receive a DMN with status=”DECLINED“.
     The process ends here!
2. (If the funds were initially available then…)
   Nuvei IBT attempts to debit the customer’s bank account.
   • If this transfer is successful, then no further notifications are sent.
     The process ends here!
     
     We recommend that you wait for five business days, where “no further notifications are received”, for you to consider the transfer successfully processed.
     For more details see the “Representment Process” section.

   • If this transfer is not successful…:
     • Due to some “decline” reason except for “insufficient funds / uncollected funds”:
       Nuvei IBT responds with “DECLINED” and you receive a DMN with status=”DECLINED“.
       The process ends here!
     • Due to “insufficient funds / uncollected funds”:
       The system begins the “Representment Process“, which attempts to debit the customer’s bank account at set time intervals.
       Each time a debit attempt is unsuccessful, you receive a DMN with status=”UPDATE“, and a representmentInformation parameter which contains the date of the next collection attempt.
       For example: “representmentInformation=R+20210310“
   • If Nuvei IBT is not able to collect the amount within their “two additional represents attempts” then:
     A final response with “DECLINED” is sent, and you receive a DMN with status=”DECLINED“.
     The process ends here!
     
     Effectively, the initial “APPROVED” response is now replaced with a “DECLINED” response.
     (An initial “DECLINED” response always remains a “DECLINED” response.)

Prerequisites and Notes

• This document assumes that you have completed all the account setup prerequisites, and are ready to integrate Nuvei IBT into your payment flow.
• Nuvei IBT only supports US-based IPs. IP addresses outside the US do not work.
• Transactions are conducted in US Dollars.
• Nuvei’s “redirection mode” is used for the following Nuvei IBT actions:
  • Nuvei IBT ACH payment (deposit) transactions.
  • For registering a new account during the Nuvei IBT withdrawal (payout) process.
• For test credentials and testing scenarios or any other assistance, contact Nuvei support.

Payment (without UPO)

You can send REST API /payment requests and include the additional Nuvei IBT parameters, as described in these steps:

1. The Nuvei IBT payment (deposit) flow begins when the customer enters an amount to deposit in the payment page.
2. Generate a sessionToken by sending a /getSessionToken request.
3. Perform the payment by sending a /payment request with its mandatory parameters including:
   • userTokenId
   • amount
   • currency
   • paymentOption.alternativePaymentMethod class containing:
     • paymentMethod: “apmgw_eCheckSelect“
   • billingAddress class containing: firstName, lastName, address, city, state, zip, country, email
   • userDetails class containing: firstName, lastName, address, city, state, zip, country, email, dateOfBirth
4. A successful request returns a paymentOption.redirectUrl.
   Redirect the customer to their bank’s site, so they can select the bank account they want to pay from.
   The customer selects the bank account from which to make their payment.
5. Nuvei IBT processes the request as described in the “Payment (Deposit) Flow” section.
6. After processing the transaction, you receive a DMN (sent to the urlDetails.notificationUrl parameter that you can provide in the request) that includes the result of the transaction (see Example Payment DMNs).

Example /payment without UPO Request

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

Example /payment without UPO Response

{
  "reason": "",
  "orderId": "36298881",
  "transactionStatus": "REDIRECT",
  "clientRequestId": "GF1XTXTBM",
  "internalRequestId": 17817111,
  "version": "1.0",
  "merchantSiteId": "126006",
  "merchantId": "2502136204546424962",
  "clientUniqueId": "695701003",
  "errCode": 0,
  "paymentOption": {
    "redirectUrl": "https://cdn-int.safecharge.com/safecharge_resources/v1/get_to_post/index.html?eyJhbGciOiJSUzI1NiJ9.eyJkZXRhaWxzIjoiNzRDQkZEODMyOUI1RDMwMjNDM0YwNUJERThGRkFEMDRGQUNEMURCQUZFMEYxM0QwMzhFQkU5RjRCMzhFMTY2RTY5NEI0QzhDMDg2RjYzMDM2RTdCMkIyREVBRjRENTIyNkM2RDg1RUE5NkI2QjIzNjEzMUVBREI0NDBGRjU0QzE0RThGM0ZCODg2QzUwQzcyMTYxMURBMkNBQzg1NzI2NjRCOEE4ODE0MThEMkJCMjBFNTAzRDE4MTRBMkJBM0M1NjM3RDBCNkFFRDU5MUVFQzk2NEQwMUE2OEFFRUQyMDBBMUJBRUQ4RUIxNDBGNEEwQkQ2OTE3MzYxMEM4Rjg1MTAwMjMxREEzQkRDNUZGMkNGOUNGRURCQkZFMTQ2REEwMDdCQUY4QUUzN0Q1Q0JEQTYzOTQyNDhGMkFEQzhFMzMyODU4NzQ5MzUyNTI2NDFFREREM0Q4ODEwQTE3RkVCNTlBMjY4ODBCMkI2NjYzRkVENjk3RjRBMDhERTFBNzVDRDdBMzk2MzBGRjJBREU1Mjk0N0FERjFFQUVFMDA4Nzg4Q0REN0RCNjM5M0QwRTNEOTFBQkVERTY3MDFBMUQ0RkU3M0M3RTQwNUQ5RjlCNzZDMUYxRjQ5QzIxMjU4RERENDVDQUFDNTNERDg4MEVBNTk2Mzk1QzBDRDQ4NUY0OTQ4M0VERURGNDJFRkQzMUJBNkIwMUYwMTFGMTVGNzAyMUI2OTRBOUQ1NTU0OEEyQ0FDNUQ3MzVBNTgyMkJCMEFDOUFCQjhBQzc1Q0UxNzc1NjI0QzY1QUQ1MDU4NTVCRDI5RjFCMjJCMDlCREExM0I1QkFFQ0ZEMTA1MUI2NTQ4QTUxQkJDNDlEOTlCQUI4MUZERjAwNzAyQTBDQ0IyQTk3MDVENzE2MkZFRUQ5RjEzN0ZGN0FGMDUwNUIyMUIwOTY2RDA2NTFFQkRDRDA1MkY0RTE4MDY5ODlCOEFBQjJDMTIxNkIzNzJDREQ5RDQ0RDQ2N0EwOEUwQjI4MkUzOTkwNjAwOTcyQ0NDNEYwQjZEMDdERDg1ODk2MDYzM0UwNkExQ0VGRTY0OEExNzBDOTA3RjA3Qzg4NDA4NDI0MzQzRjNGQjM1MDZFN0EzRkEwNkQ0MDY5M0QyQkE3MzBGQTdCNzc3NDFFQUU2NDg2NEI2NjE3MDdGMzY0MDNCMTQyOTJDMTM1NzI5NDUwQ0YxRDk3NTcxQUE5NzJDQzg1MTVGQSIsIm1lcmNoYW50X2lkIjoiU2ZDaGFyZ2UiLCJpdiI6Ijk5RTM0MEMyNzg0MkNBOTlCQkIxQzUyNzVFQUFFNURBIiwidXJsIjoiaHR0cHM6Ly9zdGFnaW5nLnZlcmlmaWVkYWNoLmNvbS9jb25zdW1lci9BY3F1aXJlSW5mb0dhdGV3YXkuZG8ifQ.EF3K5UsPQYdua_YcRd9Yefl-KemNwEMq5-EXV7QWAZUbCQglncAaAHzzlW-sxq2XcVZcZ2qbxLkQqjzkB3tItTGUDmqysL-opqOdaaz54EKeHKC5hzQIp77DucIGYQhPxfOB_eAxTOPLvZ85c3woJ37m8BH8kuJPSoAjYrZ12geEQJQx4R2VxNT3QsxxryEWZvU1yKc8mjCl011nWz6cp4LZpHIMwUwvdCMJWUeJtAxC-Q6Ec4NqP93AFki9Ln0OOvenbOEBn3UpK_BncxKu7RFOzM8w4kSf0eopKC44awlROwZaO0k0htJAUikA_W-fgeLISuMpHmWMZz6X3Ju2Bg",
    "userPaymentOptionId": "8061731",
    "card": {}
  },
  "sessionToken": "6fa38ea2-6f1a-4620-85ae-7deaf0d5f8f1",
  "userTokenId": "2J6QZH3UF9E2",
  "status": "SUCCESS"
}

Payment (with UPO)

You can allow your customer to select one of their bank accounts registered at IBT – US, represented by a UPO, and use it to perform a Nuvei IBT ACH payment (deposit), as described in these steps:

1. The Nuvei IBT ACH payment (deposit) flow begins when the customer enters an amount to deposit in the payment page.
2. Generate a sessionToken by sending a /getSessionToken request.
3. Perform the payment by sending a /payment request with its mandatory parameters including:
   • userPaymentOptionId
   • amount
   • billingAddress class containing: firstName, lastName, city, state, zip, country, email
4. A successful request returns a paymentOption.redirectUrl.
   Redirect the customer to their bank’s site, so they can confirm the bank account they want to pay from.
   The customer confirms the bank account from which to make their payment.
5. Nuvei IBT processes the request as described in the “Payment (Deposit) Flow” section.
6. After processing the transaction, you receive a DMN (sent to the urlDetails.notificationUrl parameter that you can provide in the request) that includes the result of the transaction (see Example Payment DMNs).

Example /payment with UPO Request

{
  "sessionToken": "<sessionToken from /getSessionToken>",
  "merchantId": "<your merchantId>",
  "merchantSiteId": "<your merchantSiteId>",
  "userTokenId": "<unique customer identifier in merchant system>",
  "clientRequestId": "<unique request ID in merchant system>",
  "clientUniqueId": "<unique transaction ID in merchant system>",
  "currency": "USD",
  "amount": "100",
  "paymentOption": {
    "userPaymentOptionId": "<UPO received from previous deposit>"
  },
  "deviceDetails":{
    "ipAddress":"<customer's IP address>"
  },
  "billingAddress": {
    "firstName": "John",
    "lastName": "Smith",
    "city": "Boston",
    "zip": "02460",
    "state": "MA",
    "country": "US",
    "email": "[email protected]"
  },
  "timeStamp": "<YYYYMMDDHHmmss>",
  "checksum": "<calculated checksum>"
}

Example /payment with UPO Response

{
  "reason": "",
  "orderId": "36298951",
  "transactionStatus": "REDIRECT",
  "clientRequestId": "2VXORP7A1",
  "internalRequestId": 17817211,
  "version": "1.0",
  "merchantSiteId": "126006",
  "merchantId": "2502136204546424962",
  "clientUniqueId": "695701003",
  "errCode": 0,
  "paymentOption": {
    "redirectUrl": "https://cdn-int.safecharge.com/safecharge_resources/v1/get_to_post/index.html?eyJhbGciOiJSUzI1NiJ9.eyJkZXRhaWxzIjoiRUM5OURFMkU0NjdBQUQ1QUU4NkQ3MzAwNjMzRkFFRTVDNTEwOEIxMjRENzI0NjgzREM5OEE1NTczMzU0NzY2NjFDNjc5MDgyMjhGMzU1NzlFQ0Y0RUUxM0QwNURGNTJGNkZCNjFFNjU5ODQxMTM3Q0Y2RjFFNjU3Nzc5MDI0MTg0NjE4NEJDODhFRjYyOUQ2MzkzQjc2NjQ3MzYwQUQxNzFDNUExQzJBNzE5MkEzMTYzMTlFQzlFNTY3MTlDQTNFODc2OUU0OTlEODRGQUZEMUZBRUM1RjUzNjEwREQ1QkIwRDU3Qjg1MUI2OUY1RjM0QzU4ODlFMUZFNERDQjI2NTAwRTFCM0VGNTA3MEJCMDAyRjg0ODM4MEI0MDMyRTBGQjY0NjY4REZDRjc4QzFFNjJBMDlERTYyMkE3RjEyNTQ0MkYzRkFFNUM1MzlGMzgwNkVGOTIwNTM0QUM4MjBFNDU0NTI1NzlERkM0OEQ3QkZBRUUyQTJERDZDQjRDMjE5RENCN0YzRjgyQ0Y2RDBGOTJGMzQ0Mjc1NjQ4REY1RDY2MEFDNUNEQ0Y2QzE4RDA2MzAzMEM5OTNEMUNBRjUyNDUyQjY1ODJGREQ0NUU4NjJEN0M0NDE3NDc1RDNFRkY0NkFCMzdDRUNGQ0NDM0U5OTA0REFERjBBNDY4QTFCNjI2NzA1MUM4OTVBOTkxNkQ0NjFCQ0I4QkQ0NkQzMDE4Mjc4RjE3NkEyOTI5MkI3OTYxQTUzNTk0RTA0NUJDM0IxMkUzOEI5MDhBRDkyQjE1NTI1QTA2QjVCQTU4NUZBOEE2MEQ4Q0VDOTRDMzBENDU0MUU2RENCRkM1NTJDMDFEMjc5RjBFMTczNTU1QTU4NEMzMDdGNEE2QTc4RjlGNEVCRTQ4OTVCRTA5MkEwQTQzMzE5OTg4ODA2MTQyQ0NCMjU1M0ZDM0JGQkI5M0ZCMTU5QjI1OUNGMzUxRjk2ODM5NDBFMzFFOTgzRUNBNDU5MEI1RkE5N0Q1MUNDMjc2MTUwQzZFM0I1NTlGODVGREQ0NTVCMjMzMEM5OEMyMzhDODUxODQ2NUNDRkJDNDIwODAwNEJCNzlGMTJFN0NDOTE2RDFDOTUwQkQ4RUQwQzJGRTNCRkVEQzUwNzMyNEYxMEMwNUY4NDIzQzI1MEIxMEEwRTFCMEY3OTU1NEJCMTU4N0QzMkQ5QzVDN0NGQ0Y2NTc4RTkwRTFEQUQ4NDY3Mzc2MzJGMzE0MEQ1RjMyNEVCN0JGQkQ4RDYwOEE3NDk0Rjg5MUNGMTM4QzBFQjY1NkRFOUJBNjRDOTlCQ0I3NDk3MzIzMjZCOTQyMkMyM0U3OEMwQ0I3RkVCOUZGQTQ1OTI5QyIsIm1lcmNoYW50X2lkIjoiU2ZDaGFyZ2UiLCJpdiI6IjIxQzdFNzhCQTQ5MTUyMzFGNTM1QkEzMDBGNjA3OUJDIiwidXJsIjoiaHR0cHM6Ly9zdGFnaW5nLnZlcmlmaWVkYWNoLmNvbS9jb25zdW1lci9BY3F1aXJlSW5mb0dhdGV3YXkuZG8ifQ.oJcwsoVB8wQXXNGi71Diqb3Lhm_6Vj3b5elO9w2ya67iG6IXP0jcFRWssBldiFvqlszE0t0GyEjgllvoZqXejt7GqcGmpUrGuJjrJL7T6yvnv15ApKSSNOKC_O2Q2yxU5l1IxHpY7vWkl3__oDJ0zMEjCyK4czW_B63-ZaGplfI0o0Mn3Aw1Vzoxn17UBjS7i4zRDm448wq2tnIfm9WBvFbR79Qdh6lJwUWI_xdwik8L3oR67MEC35w8SV9XCMjwX_WqOvaqk_mq1WXOxM0X1ooAmw6Tmd3jMM37od583ReT3GlbfDtU6NlBDAgrxEjwr807HGnQXSlKSMsxJoWnhw",
    "userPaymentOptionId": "8061731",
    "card": {}
  },
  "sessionToken": "1be68338-e45e-4c81-b617-e1bfb94cae3e",
  "userTokenId": "2J6QZH3UF9E2",
  "status": "SUCCESS"
}

Account Capture

When processing a withdrawal (payout) request, the account capture feature enables the merchant to redirect the user to the Nuvei IBT account capture page instead of having to collect the bank details.

The following flow describes how the customer’s account details must first be captured before processing the payout request:

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, amount, firstName, lastName, address, city, state, zip, birthdate, and ipAddress

   Example /accountCapture Request

   {
       "sessionToken":"<sessionToken from /getSessionToken>",
       "merchantId":"<your merchantId>",
       "merchantSiteId":"<your merchantSiteId>",
       "paymentMethod":"apmgw_eCheckSelect",
       "userTokenId":"<unique customer identifier in merchant system>",
       "currencyCode":"USD",
       "countryCode":"US",
       "amount":"200"
       "languageCode":"en",
       "userDetails":{
           "firstName":"John",
           "lastName":"Smith",
           "address":"22 Main Street",
           "phone":"6175551414",
           "zip":"02460",
           "city":"Boston",
           "state":"MA",
           "email":"[email protected]",
           "country": "US",
           "birthdate":"2000-06-30"
       },
       "deviceDetails":{
           "ipAddress":"<customer's IP address>"
       },
   }

   The request returns a redirectUrl.

   Example /accountCapture Response

   {
       "reason":"",
       "redirectUrl":"https://pay-pd-mint.mazooma.com/bank-select?code=3e2ccaa1-76e5-40eb-b11c-4ef56b2e98b6&merchant-return-url=https%3A%2f%2fjumpbox.safecharge.com%2fdmz%2fApmConnector%2fbankCapture%2f9E8AD967448FB187B6A7F97CE9123ED8",
       "merchantId":"2502136204546424962",
       "errCode":0,
       "sessionToken":"c02dd5dc-9119-4de1-8192-0b8cdcb02650",
       "userTokenId":"MJIKY53AK9K7",
       "internalRequestId":19287531,
       "version":"1.0",
       "status":"SUCCESS",
       "merchantSiteId":"126006"
   }

3. Use the redirectUrl to redirect the customer to the Nuvei IBT page, where the customer logs in to their bank account and confirms the payout request.
4. Once the bank account information is captured, Nuvei stores the data in a UPO record and sends a  back to you with the newly created userPaymentOptionId, which is used to proceed with the payout.
   
   

   Example /accountCapture DMN with status: APPROVED

   ...'ppp_status=OK&Status=APPROVED&ExErrCode=0&ErrCode=0&errApmCode=0&errApmDescription=&errScCode=0&errScDescription=&Reason=&ReasonCode=0&PPP_TransactionID=42757704386&userid=&merchant_unique_id=&customData=BetFanatics+Multi&productId=Cashier+Test+product&first_name=Jacob&last_name=Horrocks&email=UserID_8916977420%40gmail.com&currency=USD&customField1=&customField2=&customField3=&customField4=&customField5=&customField6=&customField7=&customField8=&customField9=&customField10=&customField11=&customField12=&customField13=&customField14=&customField15=&invoice_id=&address1=28316+N.+Castle+Rock+Dr.&address2=&country=United+States&state=NEBRASKA&city=San+Tan+Valley&zip=51501&phone1=4022189879&phone2=&phone3=&client_ip=47.28.148.169&nameOnCard=&cardNumber=&bin=&noCVV=&acquirerId=&acquirerBank=Mazooma+Direct&expMonth=&expYear=&Token=&tokenId=&AuthCode=***1634&AvsCode=&Cvv2Reply=&shippingCountry=&shippingState=&shippingCity=&shippingAddress=&shippingZip=&shippingFirstName=&shippingLastName=&shippingPhone=&shippingCell=&shippingMail=&total_discount=0.00&total_handling=0.00&total_shipping=0.00&total_tax=0.00&buyButtonProductBundleId=&merchant_site_id=244926&merchant_status=&action=&requestVersion=&message=APPROVED&merchantLocale=en_US&unknownParameters=&payment_method=apmgw_eCheckSelect&ID=&merchant_id=868246605107540895&responseTimeStamp=2023-06-13.20%3A25%3A24&buyButtonProductId=&webMasterId=&appliedPromotions=&uniqueCC=&transactionType=Sale&externalEmail=&cardCompany=&eci=&user_token_id=UserID_8916977420&user_token=auto&userPaymentOptionId=2734193346&TransactionID=2130000002760856584&ExternalaccountID=68f91747-8472-419a-bae7-6fdc1af4e26e&externalTransactionId=20230613202325336703000000&APMReferenceID=0C5AB54BD97AB10BCF7076D7D78556C8&orderTransactionId=40807183706&totalAmount=1.00&dynamicDescriptor=BetFanatics&item_name_1=Cashier+Test+product&item_number_1=&item_amount_1=1.00&item_quantity_1=1&item_discount_1=0.00&item_handling_1=0.00&item_shipping_1=0.00&feeAmount=&amountWithoutFee=&houseNumber=&customCurrency=&upoRegistrationDate=20230613&type=DEPOSIT&clientRequestId=&relatedTransactionId=&apmPayerInfo=fi_acc_type%3DPC%26acc_label%3D***1634%26fi_name%3DFIRST+INTERSTATE+BANK&sessionId=66d32afe1ed7570a4e7a385a2e2c&responsechecksum=10f3acf08d82f17b882856a4c254ac3cdf209da4569b47f78c2dcf252f64e920&advanceResponseChecksum=901f2a841060f9c8f9be7eb170bd82992b95a7c9b567ad34c9964d965627ddc1',

   Example /accountCapture DMN with status: DECLINED

   ...'ppp_status=FAIL&Status=DECLINED&ExErrCode=0&ErrCode=27&errApmCode=27&errApmDescription=&errScCode=1220&errScDescription=Consumer+abandoned+transaction&Reason=Consumer+abandoned+transaction&ReasonCode=1220&PPP_TransactionID=42760037256&userid=&merchant_unique_id=&customData=BetFanatics+Multi&productId=Cashier+Test+product&first_name=Jacob&last_name=Horrocks&email=jakehorrocks%40hotmail.com&currency=USD&customField1=&customField2=&customField3=&customField4=&customField5=&customField6=&customField7=&customField8=&customField9=&customField10=&customField11=&customField12=&customField13=&customField14=&customField15=&invoice_id=&address1=28316+N.+Castle+Rock+Dr.&address2=&country=United+States&state=ARIZONA&city=San+Tan+Valley&zip=85143&phone1=4022189879&phone2=&phone3=&client_ip=47.28.148.169&nameOnCard=&cardNumber=&bin=&noCVV=&acquirerId=&acquirerBank=Mazooma+Direct&expMonth=&expYear=&Token=&tokenId=&AuthCode=&AvsCode=&Cvv2Reply=&shippingCountry=&shippingState=&shippingCity=&shippingAddress=&shippingZip=&shippingFirstName=&shippingLastName=&shippingPhone=&shippingCell=&shippingMail=&total_discount=0.00&total_handling=0.00&total_shipping=0.00&total_tax=0.00&buyButtonProductBundleId=&merchant_site_id=244926&merchant_status=&action=&requestVersion=&message=DECLINED&merchantLocale=en_US&unknownParameters=&payment_method=apmgw_eCheckSelect&ID=&merchant_id=868246605107540895&responseTimeStamp=2023-06-13.22%3A15%3A29&buyButtonProductId=&webMasterId=&appliedPromotions=&uniqueCC=&transactionType=Sale&externalEmail=&cardCompany=&eci=&user_token_id=UserID_6196675254&user_token=auto&userPaymentOptionId=2734396956&TransactionID=2130000002761597013&externalTransactionId=20230613213246098301000000&APMReferenceID=2EDD8E5F0FE277270C992DDE871DE8D2&orderTransactionId=40810527866&totalAmount=1.00&dynamicDescriptor=BetFanatics&item_name_1=Cashier+Test+product&item_number_1=&item_amount_1=1.00&item_quantity_1=1&item_discount_1=0.00&item_handling_1=0.00&item_shipping_1=0.00&feeAmount=&amountWithoutFee=&houseNumber=&customCurrency=&upoRegistrationDate=20230614&type=DEPOSIT&clientRequestId=&relatedTransactionId=&apmPayerInfo=fi_acc_type%3Dnull%26acc_label%3Dnull%26fi_name%3Dnull&sessionId=6a853b8cdc497c7b9bdb6331da44&responsechecksum=4cf72d41fb5e1cfae733a3577c015e493a52ec3fcdd0d8955818e4b38ba6c7e1&advanceResponseChecksum=4a7bbcf03351cf2a3600d1a6841638c366fad1b95f532fed7d7b487e55ff2d38',

Payout (Withdrawal) Flow

The /payout request can only be performed using a UPO (representing the customer bank account).

Call the /payout request and include:

• userTokenId
• The relevant userPaymentOptionId
• These additional Nuvei IBT parameters: firstName, lastName, address, state, email, zip, and dateOfBirth
  If they are not already stored in the UPO, please use the /updateUser method to add them.

Example /payout Request

{
  "merchantId": "<your merchantId>",
  "merchantSiteId": "<your merchantSiteId>",
  "userTokenId": "<unique customer identifier in merchant system>",
  "clientUniqueId": "<unique transaction ID in merchant system>",
  "clientRequestId": "<unique request ID in merchant system>",
  "currency": "USD",
  "amount": "35",
  "userPaymentOption": {
    "userPaymentOptionId": "<UPO received from previous deposit>"
  },
  "deviceDetails": {
    "ipAddress": "<customer's IP address>"
  },
  "timeStamp": "<YYYYMMDDHHmmss>",
  "checksum": "<calculated checksum>"
}

Example /payout Response

{
  "reason": "",
  "transactionStatus": "APPROVED",
  "clientRequestId": "W1Q3SBGE4",
  "internalRequestId": 17817071,
  "version": "1.0",
  "transactionId": "2110000000004333013",
  "merchantSiteId": "126006",
  "merchantId": "2502136204546424962",
  "clientUniqueId": "695701003",
  "errCode": 0,
  "userPaymentOptionId": "8054521",
  "paymentMethodErrorCode": 0,
  "userTokenId": "CEBQK9OVSLJA",
  "externalTransactionId": "2110000000068709",
  "status": "SUCCESS"
}

After processing the transaction, you receive a DMN (sent to the urlDetails.notificationUrl parameter that you can provide in the request) that includes the result of the transaction (see Example Payout DMNs).

Developer Notes

• Nuvei IBT Error Codes
• Nuvei IBT Brand Requirements
• Nuvei IBT Post-Integration and Certification Checklist
• Nuvei IBT Transaction Returns

Testing

User name: user_good
Password: pass_good

When testing withdrawal transactions (using the /payout method), you can use the transaction amount value to specify which payout type (withdrawal type) to apply to the transaction.
Set the amount value:

• amount < 100 – To specify ach payout type.
  Transaction processing using the ACH network (can take 2-3 days for the funds to arrive).
• amount = 100 – To specify pending payout type.
  Payout type is not yet known.
• amount > 100 – To specify rtp payout type.
  Real-time payout (transaction processing is almost instantaneous).

Plaid Remember Me Sandbox Test Credentials

For all scenarios, the one-time password (OTP) is 123456.

Returning User – User has previously enrolled in the returning user experience by confirming their device and successfully linking an item.

Appendices

Representment Process

After submitting a successful “deposit” (payment) request, when Nuvei IBT attempts to charge the customer’s account, it is still possible for them a return a notification containing these errors: R01 (insufficient funds) or R09 (uncollected funds). If so, Nuvei IBT does not decline the deposit at that point but instead attempts to collect the funds (“representment”), up to two more times.

• If a representment (attempt to charge (debit) the customer’s bank account) is successful, then no further notifications are sent.
  The process ends here!
  We recommend that you wait for five business days, where “no further notifications are received”, for you to consider the transaction successfully processed.

• If a representment was not successful, then you receive a notification that includes the nextActionDate parameter containing the date scheduled for the next attempt to charge (debit) the customer’s bank account.
  IBT – US calculates the nextActionDate as follows:

  • Date of the 1st representment attempt: Three business days after the original return notification.
  • Date of the 2nd representment attempt: The 15th or the last day of the month, whichever comes first.
• If Nuvei IBT is not able to collect the amount after the 1st and 2nd representment attempts, then it sends a final notification that the deposit was declined.
  The process ends here!

Managing Bank Accounts

You can manage customer UPOs (representing customer bank accounts) as described below:

• Generating UPOs
• Deleting UPOs

Generating UPOs

A UPO represents a customer bank account in the Nuvei system. It is normally automatically generated and returned by a /payment request.

However, you can also generate it without needing to send a /payment request first.

Adding a UPO

1. A userTokenId is required. If your customer does not have a userTokenId yet, then create it by sending a /createUser request, including these parameters in the userDetails class: firstName, lastName, email, address, city, state, zip, dateOfBirth.
2. Sending an /addUPOAPM request can be done using either of these ways:
   • By including the Customer bank account details.
   • By including the accountID (provided by Nuvei IBT).

Press tab to open…

{
  "merchantId": "<your merchantId>",
  "merchantSiteId": "<your merchantSiteId>",
  "clientRequestId": "<unique request ID in merchant system>",
  "userTokenId": "<unique customer identifier in merchant system>",
  "paymentMethodName":"apmgw_eCheckSelect",
  "apmData":{
    "mazooma_fi_account_number": "1111222244440000", 
    "mazooma_fi_account_type": "PC",  
    "mazooma_fi_routing": "021000021" 
  },
  "timeStamp": "<YYYYMMDDHHmmss>",
  "checksum": "<calculated checksum>"
}

{
  "merchantId": "<your merchantId>",
  "merchantSiteId": "<your merchantSiteId>",
  "clientRequestId": "<unique request ID in merchant system>",
  "userTokenId": "<unique customer identifier in merchant system>",
  "paymentMethodName":"apmgw_eCheckSelect",
  "apmData":{
    "accountID": "5aafb2e6-1e05-4c77-9077-e512324cf099"
  },
  "timeStamp": "<YYYYMMDDHHmmss>",
  "checksum": "<calculated checksum>"
}

Example /addUPOAPM Response

{
  "reason": "",
  "merchantId": "2502136204546424962",
  "errCode": 0,
  "clientRequestId": "HWMTWQ2RT",
  "userPaymentOptionId": 8052151,
  "internalRequestId": 17817221,
  "version": "1.0",
  "status": "SUCCESS",
  "merchantSiteId": "126006"
}

Deleting UPOs

Nuvei IBT recommends deleting old UPOs (representing customer bank accounts), so as not to display more than three customer bank accounts to the customer at any time (even though technically, there is no limit to the number of customer bank accounts in the Nuvei IBT system).

Follow these steps:

1. Retrieve a list of your customer’s UPOs by calling the /getUserUPOs method. If you find that the customer already has more than three UPOs in the system, then older UPOs can be identified by comparing the upoRegistrationDate parameters of the UPOs returned.
2. Delete the relevant UPOs by calling the /deleteUPO method.
   Once a UPO is deleted, it is not displayed in the customer’s payment page.
   
   The user can always re-register and deposit with a previously deleted bank account. The system simply generates a new UPO again.

Example Payment DMNs

DMNs include Nuvei IBT-specific parameters (in addition to general transaction information):

apmPayerInfo DMN Parameter

This contains additional customer information received from Nuvei IBT.
apmPayerInfo uses the following syntax operators:

• %26 – Separates parameter fields.
  
• %3D – Represents “=”.

Example of apmPayerInfo:

apmPayerInfo=fi_acc_type%3DPC%26acc_label%3D************0000%26fi_name%3DCHASE

Where:

• • fi_acc_type: Financial institution type. Possible values:
    • PC: Personal Checking
    • PS: Personal Savings
  • acc_label: The last 4 digits of the bank account number.
  • fi_name: Name of the bank.

ExternalaccountID DMN Parameter

This contains the accountID which is the token received from Nuvei IBT that represents the customer’s bank account.

Example of ExternalaccountID:

ExternalaccountID=5aafb2e6-1e05-4c77-9077-e512324cf099

Example /payment DMN with status: APPROVED

...'ppp_status=OK&Status=APPROVED&ExErrCode=0&ErrCode=0&errApmCode=0&errApmDescription=&errScCode=0&errScDescription=&Reason=&ReasonCode=0&PPP_TransactionID=36505121&userid=TQ2B5E77HFNP&merchant_unique_id=695701003&customData=Custom+Data%21&productId=&first_name=ALBERTA&last_name=BOBBETHCHARLESON&email=accountholder0%40example.com&currency=USD&clientUniqueId=695701003&customField1=customField1-value&customField2=customField2-value&customField3=&customField4=&customField5=&customField6=&customField7=&customField8=&customField9=&customField10=&customField11=&customField12=&customField13=&customField14=&customField15=&invoice_id=&address1=2992+Cameron+Road&address2=&country=United+States&state=NEW+YORK&city=Newark&zip=14236&phone1=1112223333&phone2=&phone3=&client_ip=192.168.2.38&nameOnCard=&cardNumber=&bin=&acquirerId=&expMonth=&expYear=&Token=&tokenId=&AuthCode=************0000&AvsCode=&Cvv2Reply=&shippingCountry=US&shippingState=NEW+YORK&shippingCity=Newark&shippingAddress=2992+Cameron+Road&shippingZip=14236&shippingFirstName=ALBERTA&shippingLastName=BOBBETHCHARLESON&shippingPhone=1112223333&shippingCell=&shippingMail=accountholder0%40example.com&total_discount=0.00&total_handling=0.00&total_shipping=0.00&total_tax=0.00&buyButtonProductBundleId=&merchant_site_id=126006&merchant_status=&action=&requestVersion=&message=APPROVED&merchantLocale=&unknownParameters=&payment_method=apmgw_eCheckSelect&ID=&merchant_id=2502136204546424962&responseTimeStamp=2021-11-03.07%3A20%3A55&buyButtonProductId=&webMasterId=31NS0LCZGIPC&appliedPromotions=&uniqueCC=&transactionType=Sale&externalEmail=&cardCompany=&eci=&user_token_id=TQ2B5E77HFNP&userPaymentOptionId=8091901&TransactionID=2110000000004789463&ExternalaccountID=5aafb2e6-1e05-4c77-9077-e512324cf099&externalTransactionId=20211103072009610142000000&APMReferenceID=47C1358F56F6B0ED81F88F2B0FB42EE7&orderTransactionId=18195031&totalAmount=1.00&dynamicDescriptor=CashierAPIDescriptor123456789101112131415&item_name_1=Item+1U&item_number_1=&item_amount_1=1.00&item_quantity_1=1&item_discount_1=0.00&item_handling_1=0.00&item_shipping_1=0.00&feeAmount=&amountWithoutFee=&houseNumber=&customCurrency=&upoRegistrationDate=20211103&type=DEPOSIT&clientRequestId=455BC4DDF&relatedTransactionId=&apmPayerInfo=fi_acc_type%3DPC%26acc_label%3D************0000%26fi_name%3DCHASE&responsechecksum=84c9eafc3386e5c393dbda7f96691b66&advanceResponseChecksum=074333e52e7c539ce5d0565af16504a8',

Example /payment DMN with status: UPDATE

...'ppp_status=OK&Status=UPDATE&ExErrCode=0&ErrCode=0&errApmCode=0&errApmDescription=&errScCode=0&errScDescription=&Reason=&ReasonCode=0&PPP_TransactionID=35830451&userid=UID&merchant_unique_id=MUID&customData=QA+test+merchant&productId=PID&first_name=Michael&last_name=Quinn&email=test%40mymail.com&currency=USD&customField1=&customField2=&customField3=&customField4=&customField5=&customField6=&customField7=&customField8=&customField9=&customField10=&customField11=&customField12=&customField13=&customField14=&customField15=&invoice_id=&address1=800+Sheridan+Ave&address2=15&country=United+States&state=NEW+JERSEY&city=Elizabeth&zip=07208&phone1=0987654321&phone2=&phone3=&client_ip=87.120.11.254&nameOnCard=&cardNumber=&bin=&acquirerId=&expMonth=&expYear=&Token=&tokenId=&AuthCode=&AvsCode=&Cvv2Reply=&shippingCountry=&shippingState=&shippingCity=&shippingAddress=&shippingZip=&shippingFirstName=&shippingLastName=&shippingPhone=&shippingCell=&shippingMail=&total_discount=0.00&total_handling=0.00&total_shipping=0.00&total_tax=0.00&buyButtonProductBundleId=&merchant_site_id=3111&merchant_status=&action=&requestVersion=&message=UPDATE&merchantLocale=en_US&unknownParameters=&payment_method=apmgw_eCheckSelect&ID=&merchant_id=4972436454212160565&responseTimeStamp=2021-03-05.15%3A34%3A30&buyButtonProductId=&webMasterId=&appliedPromotions=&uniqueCC=&transactionType=Sale&externalEmail=&cardCompany=&eci=&user_token_id=MAZTE1234&user_token=auto&userPaymentOptionId=7999181&TransactionID=2110000000003234581&APMReferenceID=07FAF21F46C5866AD38701E10962847F&orderTransactionId=17911911&totalAmount=15.00&dynamicDescriptor=QA+Test+site&item_name_1=ItemName&item_number_1=&item_amount_1=15.00&item_quantity_1=1&item_discount_1=0.00&item_handling_1=0.00&item_shipping_1=0.00&feeAmount=&amountWithoutFee=&houseNumber=&customCurrency=&externalToken_blockedCard=&externalToken_cardAcquirerId=&externalToken_cardAcquirerName=&externalToken_cardBin=&externalToken_cardBrandId=&externalToken_cardBrandName=&externalToken_cardExpiration=&externalToken_cardLength=&externalToken_cardMask=&externalToken_cardName=&externalToken_cardTypeId=&externalToken_cardTypeName=&externalToken_clubName=&externalToken_creditCompanyId=&externalToken_creditCompanyName=&externalToken_extendedCardType=&externalToken_Indication=&externalToken_tokenValue=&externalToken_tokenProvider=&upoRegistrationDate=20210302&type=DEPOSIT&clientRequestId=&relatedTransactionId=&representmentInformation=R+20210310&responsechecksum=e0cee5b3a3e5c63ad4368b7a52faa33d&advanceResponseChecksum=7f2c94753bac4937478c25244a004636',

Example /payment DMN with status: DECLINED

...'ppp_status=FAIL&Status=DECLINED&ExErrCode=0&ErrCode=99&errApmCode=99&errApmDescription=&errScCode=1133&errScDescription=Customer+Opt-Out&Reason=Customer+Opt-Out&ReasonCode=1133&PPP_TransactionID=374445808&userid=21b090d6_187516&merchant_unique_id=sfpgssqkzp&customData=&productId=&first_name=freqw&last_name=rfqew&email=mykyta.sopov%2Btest129%40patrianna.com&currency=USD&clientUniqueId=sfpgssqkzp&customField1=&customField2=&customField3=&customField4=&customField5=&customField6=&customField7=&customField8=&customField9=&customField10=&customField11=&customField12=&customField13=&customField14=&customField15=&invoice_id=&address1=2992+cameron+road&address2=&country=United+States&state=NEW+YORK&city=newark&zip=14236&phone1=&phone2=&phone3=&client_ip=&nameOnCard=&cardNumber=&bin=&noCVV=&acquirerId=&acquirerBank=Mazooma+Direct&expMonth=&expYear=&Token=&tokenId=&AuthCode=&AvsCode=&Cvv2Reply=&shippingCountry=&shippingState=&shippingCity=&shippingAddress=&shippingZip=&shippingFirstName=&shippingLastName=&shippingPhone=&shippingCell=&shippingMail=&total_discount=0.00&total_handling=0.00&total_shipping=0.00&total_tax=0.00&buyButtonProductBundleId=&merchant_site_id=215858&merchant_status=&action=&requestVersion=&message=DECLINED&merchantLocale=&unknownParameters=&payment_method=apmgw_eCheckSelect&ID=&merchant_id=9179488468655786942&responseTimeStamp=2023-07-02.10%3A58%3A27&buyButtonProductId=&webMasterId=sdk_java_ver1.7.0&appliedPromotions=&uniqueCC=&transactionType=Sale&externalEmail=&cardCompany=&eci=&user_token_id=21b090d6_187516&userPaymentOptionId=92154608&TransactionID=711000000024398802&externalTransactionId=20230702105701673654000000&APMReferenceID=4F52E1C7934DEA283711C20BBE6369B2&orderTransactionId=1206362878&totalAmount=4.99&dynamicDescriptor=%3F&item_name_1=NA&item_number_1=&item_amount_1=4.99&item_quantity_1=1&item_discount_1=0.00&item_handling_1=0.00&item_shipping_1=0.00&feeAmount=&amountWithoutFee=&houseNumber=&customCurrency=&upoRegistrationDate=20230630&type=DEPOSIT&clientRequestId=535b312a-0067-4b82-be79-ed8fd8c33f53&relatedTransactionId=&apmPayerInfo=fi_acc_type%3Dnull%26acc_label%3Dnull%26fi_name%3Dnull&sessionId=63ea3bb190e43e7a170a3e911ed5&responsechecksum=c97c784fe38a25168c3b21242c287411b9baff3e6003ee7f0c2796a6085bb9ed&advanceResponseChecksum=632b3264363b256e7aef6134f813ce16d9c03c2fe70d197c1a539ad72ee6abe3',

Example Payout DMNs

DMNs include Nuvei IBT-specific parameters (in addition to general transaction information).

apmPayerInfo DMN Parameter

This contains additional customer information received from Nuvei IBT.
apmPayerInfo uses the following syntax operators:

• %2C – Separates parameter fields.
  
• %3D – Represents “=”.

You can see which payout type (withdrawal type) was used for the transaction.
Possible values:

• ach  – The ACH network (can take 2-3 days for the funds to arrive).
• pending – Payout type is not yet known.
• rtp – Real-time payout (transaction processing is almost instantaneous).

Example of apmPayerInfo:

apmPayerInfo=payment_method%3Dach

Example /payout DMN with status: APPROVED

...'ppp_status=OK&Status=APPROVED&ExErrCode=0&ErrCode=0&errApmCode=0&errApmDescription=&errScCode=0&errScDescription=&Reason=&ReasonCode=0&PPP_TransactionID=350355388&userid=lkjliouoj08&merchant_unique_id=&customData=Jake+Test+Account&productId=&first_name=&last_name=&email=&currency=USD&customField1=&customField2=&customField3=&customField4=&customField5=&customField6=&customField7=&customField8=&customField9=&customField10=&customField11=&customField12=&customField13=&customField14=&customField15=&invoice_id=&address1=&address2=&country=&state=&city=&zip=&phone1=&phone2=&phone3=&client_ip=&nameOnCard=&cardNumber=&bin=&noCVV=&acquirerId=null&expMonth=&expYear=&Token=&tokenId=&AuthCode=&AvsCode=&Cvv2Reply=&shippingCountry=&shippingState=&shippingCity=&shippingAddress=&shippingZip=&shippingFirstName=&shippingLastName=&shippingPhone=&shippingCell=&shippingMail=&total_discount=0.00&total_handling=0.00&total_shipping=0.00&total_tax=0.00&buyButtonProductBundleId=&merchant_site_id=224428&merchant_status=&action=&requestVersion=&message=APPROVED&merchantLocale=&unknownParameters=&payment_method=apmgw_eCheckSelect&ID=&merchant_id=2439523627382132721&responseTimeStamp=2023-01-12.19%3A31%3A58&buyButtonProductId=&webMasterId=&appliedPromotions=&uniqueCC=null&transactionType=Credit&externalEmail=&cardCompany=&user_token_id=lkjliouoj08&userPaymentOptionId=85975828&TransactionID=811000000001623332&externalTransactionId=20230112193157465559000000&totalAmount=20.0&dynamicDescriptor=test&feeAmount=&houseNumber=&customCurrency=&upoRegistrationDate=20230112&type=DEPOSIT&clientRequestId=20230112123156&relatedTransactionId=&apmPayerInfo=payment_method%3Dach%2C&responsechecksum=5b4fac441fc81576271ca3478a446a747d7925e59c9c953eb7cd93f684e840a0&advanceResponseChecksum=b35bc14052464550989efdd8881cffc5e8bf17f44b16b2b9387be0d3b4c08e98',

Example /payout DMN with status: DECLINED

...'ppp_status=FAIL&Status=DECLINED&ExErrCode=0&ErrCode=101258&errApmCode=0&errApmDescription=&errScCode=0&errScDescription=&Reason=E108-Invalid+token.&ReasonCode=0&PPP_TransactionID=376537268&userid=TestToken01&merchant_unique_id=20230712154647&customData=Sunflower+Ltd&productId=&first_name=&last_name=&email=&currency=USD&clientUniqueId=20230712154647&customField1=&customField2=&customField3=&customField4=&customField5=&customField6=&customField7=&customField8=&customField9=&customField10=&customField11=&customField12=&customField13=&customField14=&customField15=&invoice_id=&address1=&address2=&country=&state=&city=&zip=&phone1=&phone2=&phone3=&client_ip=&nameOnCard=&cardNumber=&bin=&noCVV=&acquirerId=null&expMonth=&expYear=&Token=&tokenId=&AuthCode=&AvsCode=&Cvv2Reply=&shippingCountry=&shippingState=&shippingCity=&shippingAddress=&shippingZip=&shippingFirstName=&shippingLastName=&shippingPhone=&shippingCell=&shippingMail=&total_discount=0.00&total_handling=0.00&total_shipping=0.00&total_tax=0.00&buyButtonProductBundleId=&merchant_site_id=239508&merchant_status=&action=&requestVersion=&message=DECLINED&merchantLocale=&unknownParameters=&payment_method=apmgw_eCheckSelect&ID=&merchant_id=314900635938272034&responseTimeStamp=2023-07-12.12%3A46%3A50&buyButtonProductId=&webMasterId=&appliedPromotions=&uniqueCC=null&transactionType=Credit&externalEmail=&cardCompany=&user_token_id=TestToken01&userPaymentOptionId=92678378&TransactionID=711000000024646181&totalAmount=100.0&dynamicDescriptor=test&feeAmount=&houseNumber=&customCurrency=&upoRegistrationDate=20230712&type=DEPOSIT&clientRequestId=&relatedTransactionId=&responsechecksum=6bb6f5844507d35118fa2d03e9f24d84c40ae7cea8ca5ae43e30ba306417430f&advanceResponseChecksum=cc6ec38d379ba244d304d083e6768a9042a3f01268f15864752686498a82fc37',