Attributes

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

Introduction

Mazooma is a US bill payment option that processes payments and withdrawals via the US-based Automated Clearing House (ACH) network.

Supported Countries

• United States

Supported Currencies

• USD

Mazooma ACH Transactions

This is a summary of the general process:

• The first time that you perform a deposit to Mazooma 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, Mazooma 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 Mazooma ACH transactions.
  For more details, see the Managing Bank Accounts section.
• Subsequent deposits to Mazooma are performed by sending a Payment (with UPO).
• Withdrawals are performed by sending a Payout (withdrawal) request to Mazooma.

Payment (Deposit) Flow

Mazooma 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.

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

1. Mazooma first checks for the availability of the requested amount in the customer’s bank account.
   • If the funds are available:
     Mazooma responds with “APPROVED” and you receive a Direct Merchant Notification (DMN) with “status=APPROVED“.
     Mazooma 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):
     Mazooma responds with “DECLINED” and you receive a DMN with status=”DECLINED“.
     The process ends here!
2. (If the funds were initially available then…)
   Mazooma 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”:
       Mazooma 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 Mazooma 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 Mazooma into your payment flow.
• Mazooma 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 Mazooma actions:
  • Mazooma ACH payment (deposit) transactions.
  • For registering a new account during the Mazooma withdrawal (payout) process.
• Test credentials and testing scenarios should be obtained directly from Mazooma. You can contact Nuvei support for assistance.

Payment (without UPO)

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

1. The Mazooma 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:
   • 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. Mazooma 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 Mazooma, represented by a UPO, and use it to perform a Mazooma ACH Payment (deposit), as described in these steps:

1. The Mazooma 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. Mazooma 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 Mazooma’s 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 Mazooma’s 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 Mazooma 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

• IBT Error Codes
• IBT Brand Requirements
• IBT Post-Integration and Certification Checklist
• 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).

Appendices

Representment Process

After submitting a successful “deposit” (payment) request, when Mazooma 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, Mazooma 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.
  Mazooma 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 Mazooma is not able to collect the amount after the 1st and 2nd representment attempts, then they send 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 Mazooma).

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

Mazooma 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 Mazooma 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 Mazooma specific parameters (in addition to general transaction information):

apmPayerInfo DMN Parameter

This contains additional customer information received from Mazooma.
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 Mazooma 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 Mazooma specific parameters (in addition to general transaction information).

apmPayerInfo DMN Parameter

This contains additional customer information received from Mazooma.
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',