- 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:
- 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“. - If the funds are NOT available (or for some other “decline” reason):
Mazooma responds with “DECLINED” and you receive a DMN withstatus
=”DECLINED“.
The process ends here!
- If the funds are available:
- (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!
- 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 withstatus
=”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 withstatus
=”UPDATE“, and arepresentmentInformation
parameter which contains the date of the next collection attempt.
For example: “representmentInformation=R+20210310
“
- Due to some “decline” reason except for “insufficient funds / uncollected funds”:
- 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 withstatus
=”DECLINED“.
The process ends here!
- If this transfer is successful, then no further notifications are sent.
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:
- The Mazooma ACH Payment (deposit) flow begins when the customer enters an
amount
to deposit in the payment page. - Generate a
sessionToken
by sending a/getSessionToken
request. - Perform the payment by sending a
/payment
request with its mandatory parameters including:userTokenId
amount
currency
paymentOption.alternativePaymentMethod
block containing:paymentMethod
: “apmgw_eCheckSelect“
billingAddress
block containing:firstName
,lastName
,address
,city
,state
,zip
,country
,email
userDetails
block containing:firstName
,lastName
,address
,city
,state
,zip
,country
,email
,dateOfBirth
- 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. - Mazooma processes the request as described in the “Payment (Deposit) Flow” section.
- 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:
- The Mazooma ACH Payment (deposit) flow begins when the customer enters an
amount
to deposit in the payment page. - Generate a
sessionToken
by sending a/getSessionToken
request. - Perform the payment by sending a
/payment
request with its mandatory parameters including:userPaymentOptionId
amount
billingAddress
block containing:firstName
,lastName
,city
,state
,zip
,country
,email
- 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. - Mazooma processes the request as described in the “Payment (Deposit) Flow” section.
- 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:
- Generate a
sessionToken
. Press here for details. - 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
, andipAddress
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" }
- 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. - 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 withstatus
: 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¤cy=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 withstatus
: 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¤cy=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
, anddateOfBirth
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 specifyach
payout type.
Transaction processing using the ACH network (can take 2-3 days for the funds to arrive).amount
= 100 – To specifypending
payout type.
Payout type is not yet known.amount
> 100 – To specifyrtp
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! - 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. - 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
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
- A
userTokenId
is required. If your customer does not have auserTokenId
yet, then create it by sending a/createUser
request, including these parameters in theuserDetails
block:firstName
,lastName
,email
,address
,city
,state
,zip
,dateOfBirth
. - 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…
Send an /addUPOAPM
request using the userTokenId
, including the following Mazooma parameters in the apmData
block:
Parameter | Description |
---|---|
apmData.mazooma_fi_account_number | The customer's bank account. |
apmData.mazooma_fi_account_type | The customer’s financial institution type. Possible values:
|
apmData.mazooma_fi_routing | The customer’s financial institution ABA number. (9-digits including leading zeros) |
Example /addUPOAPM
Request using Customer Bank Account Details
{ "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>" }
Send an /addUPOAPM
request using the userTokenId
, including the apmData.accountID
parameter.
(The accountID
is the token provided by Mazooma, which represents the customer’s bank account in their system.)
Example /addUPOAPM
Request using the accountID
{ "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>" }
- Using: Customer Bank Account Details
-
Send an
/addUPOAPM
request using theuserTokenId
, including the following Mazooma parameters in theapmData
block:
Parameter Description apmData.mazooma_fi_account_number
The customer's bank account. apmData.mazooma_fi_account_type
The customer’s financial institution type.
Possible values:- "
PC
" (personal checking) - "
PS
" (personal savings)
apmData.mazooma_fi_routing
The customer’s financial institution ABA number.
(9-digits including leading zeros)Example
/addUPOAPM
Request using Customer Bank Account Details{ "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>" }
- "
-
Using:
accountID
-
Send an
/addUPOAPM
request using theuserTokenId
, including theapmData.accountID
parameter.
(TheaccountID
is the token provided by Mazooma, which represents the customer’s bank account in their system.)Example
/addUPOAPM
Request using the accountID{ "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:
- 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 theupoRegistrationDate
parameters of the UPOs returned. - Delete the relevant UPOs by calling the
/deleteUPO
method.
Once a UPO is deleted, it is not displayed in the customer’s payment page.
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 CheckingPS
: 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¤cy=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¤cy=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¤cy=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=¤cy=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=¤cy=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',