Mazooma
Mazooma is an online payment method in the US that processes payments (deposits) and withdrawals via the US-based ACH (automated clearing house) network. The Paysafe Payments API supports Mazooma as a payment instrument.
Setup Requirements
For Paysafe to create a test account in sandbox and production environment, contact Mazooma and get the following details.
- Merchant ID
-
Merchant Site ID
-
Merchant Secret Key
Certification Requirements
Each merchant is required to go through a certification process to support Mazooma as a payment method. For more information, see Mazooma Developer site.
Transaction types
Paysafe supports the following transaction types:
- Payments - Used to transfer money from customer's bank account to merchant account. Post successful payments, merchant credits the customer's wallet.
- Withdrawal - Used to transfer money from merchant account to customer's bank account.
Typical Scenarios
Payments
When you want to process a payment request, follow these steps:
Make a Verification call
A verification call is used to fetch User's saved bank accounts at Mazooma end.
- Create a Payment Handle with the transactionType parameter set to VERIFICATION and the paymentType parameter set to MAZOOMA
- POST: paymenthub/v1/paymenthandles
- You will receive "paymentHandleToken" in the response. The response should have "status" as PAYABLE.
- Use the "paymentHandleToken" to process the Verification API.
- POST: paymenthub/v1/verifications
- In Verification API response, you will get status as COMPLETED, you will get bankToken (mazooma.achBankAccounts.paymentHandleToken) for each account.
- If no bank accounts are added in Mazooma then you will get the status as FAILED.
- Store the bankToken at your end
The BankToken (mazooma.achBankAccounts.paymentHandleToken) is a unique identifier for each bank account of the user and remains same. The BankToken is later used to create a Single-Use Payment Handle Token which is used to make the payment for each unique transaction. At Mazooma end, Saved Banks are referred as UPO (User Payment Option). In Paysafe APIs, we refer Saved Bank or UPO as bankToken (mazooma.achBankAccounts.paymentHandleToken).
Make a Payment call
User with bankToken
- Create a Payment Handle with the transactionType parameter set to PAYMENT and the paymentType parameter set to MAZOOMA.
- POST: paymenthub/v1/paymenthandles
- Since the customer has to bankToken:
- Pass the consumerid along with bankToken in the mazooma object.
- You will receive "paymentHandleToken" in the response. The response should have "status" as PAYABLE.
- Use the paymentHandleToken returned in the response to process the Payment request via Payments API using the private key. You must initiate a POST request to the endpoint:
- POST: paymenthub/v1/payments
User without bankToken
- Create a Payment Handle with the transactionType parameter set to PAYMENT and the paymentType parameter set to MAZOOMA.
- Post : paymenthub/v1/paymenthandles
- Since the customer has to complete payment by selecting bank account on Plaid page, Paysafe returns a response with the following:
- The action parameter is set to REDIRECT
- A redirect_payment link points to the Plaid redirect URL
- Redirect the customer to the Plaid redirect URL.
- On redirecting the customer to redirection link, status of the Payment Handle becomes PAYABLE and you will be notified with webhook for PAYMENT_HANDLE_PAYABLE event
- On redirection page, customer selects the bank, provides credentials, and processes the transaction.
- On redirecting the customer to redirection link, status of the Payment Handle becomes PAYABLE and you will be notified with webhook for PAYMENT_HANDLE_PAYABLE event
- Use the paymentHandleToken returned in the response to process the Payment request via Payments API using the private key. You must initiate a POST request to the endpoint:
- POST: paymenthub/v1/payments
- You will receive bankToken (mazooma.achBankAccounts.paymentHandleToken) in in the response. The response should have "status" as COMPLETED
- The bankToken can be used in the "User with bankToken" flow
Withdrawal
When you want to process a withdrawal request, you would do the following:
Make a Verification call
Verification call is used to fetch User's saved bank accounts at Mazooma end.
- Create a Payment Handle with the transactionType parameter set to VERIFICATION and the paymentType parameter set to MAZOOMA
- POST: paymenthub/v1/paymenthandles
- You will receive "paymentHandleToken" in the response. The response should have "status" as PAYABLE.
- Use the "paymentHandleToken" to process the Verification API.
- POST: paymenthub/v1/verifications
- In Verification API response, you will get status as COMPLETED, you will get bankToken (mazooma.achBankAccounts.paymentHandleToken) for each account.
- If no bank accounts are added in Mazooma then you will get the status as FAILED.
- Store the bankToken at your end.
The BankToken (mazooma.achBankAccounts.paymentHandleToken) is a unique identifier for each bank account of the user and remains same. The BankToken is later used to create a Single-Use Payment Handle Token which is used to make the payment for each unique transaction. At Mazooma end, Saved Banks are referred as UPO (User Payment Option). In Paysafe APIs, we refer Saved Bank or UPO as bankToken (mazooma.achBankAccounts.paymentHandleToken).
Make a Withdrawal call
User with bankToken
- Create a Payment Handle with the transactionType parameter set to STANDALONE_CREDIT and the paymentType parameter set to MAZOOMA.
- POST: paymenthub/v1/paymenthandles
- Since the customer has to bankToken:
- Pass the consumerid along with bankToken in the mazooma object.
- You will receive "paymentHandleToken" in the response. The response should have "status" as PAYABLE.
- Use the paymentHandleToken returned in the response to process the withdrawal request via Payments API using the private key. You must initiate a POST request to the endpoint:
- POST: paymenthub/v1/standalonecredits
APIs to use
Delete a Bank Account
Make a delete bank account request using HTTP method DELETE.
https://{{host}}:{{port}}/paymenthub/v1/registrations/mazooma.registrationId/achbankaccounts/mazooma.achBankAccounts.id
You will get "mazooma.registrationId" and "mazooma.achBankAccounts.id" from Verification API response.
Delete a bank account response
{ "id": "e1915843-bc19-48e9-8ac5-3eed98da72", "paymentHandleToken": "BARmCEZM0j1ldnMY", "bankName": "CHASE" }
API Contracts
You have to pass Mazooma object in all the payment Handle requests.
consumerId: It is a unique Id for each customer.
Verification
Verification Payment Handle Request Example
{
"merchantRefNum": "SriTest-1644827808",
"transactionType": "VERIFICATION",
"paymentType": "MAZOOMA",
"amount": 100,
"currencyCode": "USD",
"dupCheck": true,
"liveMode": true,
"mazooma": {
"consumerId": "PP_100222"
},
"profile": {
"firstName": "ALBERTA",
"lastName": "BOBBETHCHARLESON",
"email": "accountholder0@example.com",
"dateOfBirth": {
"day": "23",
"month": "12",
"year": "1990"
},
"phone": 1234567890
},
"billingDetails": {
"street1": "Queen Street West",
"street2": "Queen Street",
"city": "Imphal",
"state": "NY",
"country": "US",
"zip": "14236"
},
"returnLinks": [
{
"rel": "default",
"href": "http://www.amazon.ca"
},
{
"rel": "on_failed",
"href": "http://www.costco.ca"
},
{
"rel": "on_cancelled",
"href": "http://www.bestbuy.ca"
}
]
}
Verification Payment Handle Response Example
{
"id": "826dc476-0feb-417f-9f26-0f1ffe4e6aef",
"paymentType": "MAZOOMA",
"paymentHandleToken": "PHfS2VUcFdlzUOLo",
"merchantRefNum": "SriTest-1644827349",
"currencyCode": "USD",
"txnTime": "2022-02-14T08:29:09Z",
"billingDetails": {
"street": "Queen Street West",
"street2": "Queen Street",
"city": "Imphal",
"zip": "14236",
"state": "NY",
"country": "US"
},
"customerIp": "10.152.253.42",
"status": "PAYABLE",
"liveMode": false,
"simulator": "EXTERNAL",
"action": "NONE",
"amount": 100,
"timeToLiveSeconds": 899,
"gatewayResponse": {
"processor": "MAZOOMA"
},
"returnLinks": [
{
"rel": "on_cancelled",
"href": "http://www.bestbuy.ca"
},
{
"rel": "on_failed",
"href": "http://www.costco.ca"
},
{
"rel": "default",
"href": "http://www.amazon.ca"
}
],
"transactionType": "VERIFICATION",
"updatedTime": "2022-02-14T08:29:09Z",
"statusTime": "2022-02-14T08:29:09Z",
"mazooma": {
"consumerId": "PP_100222"
},
"profile": {
"firstName": "ALBERTA",
"lastName": "BOBBETHCHARLESON",
"email": "accountholder0@example.com",
"dateOfBirth": {
"day": 23,
"month": 12,
"year": 1990
},
"phone": "1234567890"
}
}
Verification Request Example
{
"paymentHandleToken": "PH7qGLyvMxTbwyeY",
"merchantRefNum": "mer_ref_1644827397",
"amount": 100,
"customerIp": "172.10.12.64",
"dupCheck": false,
"description": "Winning payment from Loto 649"
}
Verification Response Example
{
"id": "dc04b025-796a-4538-a738-a2ff0b83a11e",
"paymentType": "MAZOOMA",
"merchantRefNum": "SriTest-1644827349",
"currencyCode": "USD",
"txnTime": "2022-02-14T08:29:27Z",
"billingDetails": {
"street1": "Queen Street West",
"street2": "Queen Street",
"city": "Imphal",
"zip": "14236",
"state": "NY",
"country": "US"
},
"status": "COMPLETED",
"amount": 100,
"updatedTime": "2022-02-14T08:29:28Z",
"statusTime": "2022-02-14T08:29:28Z",
"liveMode": false,
"simulator": "EXTERNAL",
"gatewayResponse": {
"processor": "MAZOOMA"
},
"mazooma": {
"consumerId": "PP_100222",
"achBankAccounts": [
{
"id": "4a641804-be44-41b9-966d-8075035fa531",
"lastDigits": "99",
"bankName": "CHASE",
"paymentToken": "BAUEQlIPBN4XDpzr",
"allowedTypes": [
"PAYMENT",
"STANDALONE_CREDIT"
]
},
{
"id": "8bc1f585-2e60-4d61-9330-a1b6bf9d0e6c",
"lastDigits": "99",
"bankName": "CHASE",
"paymentToken": "BA1v8EaBkkVOKIuE",
"allowedTypes": [
"PAYMENT",
"STANDALONE_CREDIT"
]
},
{
"id": "af92bcfb-c338-45e9-83ed-e4bf87858727",
"lastDigits": "99",
"bankName": "CHASE",
"paymentToken": "BARKbHKW2qOLdstG",
"allowedTypes": [
"PAYMENT",
"STANDALONE_CREDIT"
]
}
],
"registrationId": "b0a7ae1b-1ffc-41ae-89d4-b70be1087642"
},
"profile": {
"firstName": "ALBERTA",
"lastName": "BOBBETHCHARLESON",
"email": "accountholder0@example.com",
"dateOfBirth": {
"day": 23,
"month": 12,
"year": 1990
},
"phone": "1234567890"
}
}
"allowedTypes": [ "PAYMENT", "STANDALONE_CREDIT" ] This signifies that the bankToken can be used for both PAYMENT/Deposit and STANDALONE_CREDIT/Withdrawal
Payment Handle Request Example without bankToken
{
"merchantRefNum": "66ba92be-630c-4762-a89f-7cceefb88b9d",
"transactionType": "PAYMENT",
"paymentType": "MAZOOMA",
"amount": 100,
"currencyCode": "USD",
"customerIp": "172.0.0.1",
"mazooma": {
"consumerId": "PP_100222"
},
"profile": {
"firstName": "ALBERTA",
"lastName": "BOBBETHCHARLESON",
"email": "accountholder0@example.com",
"dateOfBirth": {
"day": "23",
"month": "12",
"year": "1990"
},
"phone": 1234567890
},
"billingDetails": {
"street1": "Queen Street West",
"street2": "Queen Street",
"city": "Imphal",
"state": "NY",
"country": "US",
"zip": "14236"
},
"merchantDescriptor": {
"dynamicDescriptor": "OnlineStore",
"phone": "12345678"
},
"returnLinks": [
{
"rel": "default",
"href": "http://www.amazon.ca"
},
{
"rel": "on_failed",
"href": "http://www.costco.ca"
},
{
"rel": "on_cancelled",
"href": "http://www.bestbuy.ca"
}
]
}
Payment Handle Request Example with bankToken
{
"merchantRefNum": "ba7dd492-aac3-4147-9857-d98aa062a4ab",
"transactionType": "PAYMENT",
"paymentType": "MAZOOMA",
"amount": 100,
"currencyCode": "USD",
"customerIp": "172.0.0.1",
"mazooma": {
"consumerId": "KK_213",
"ach": {
"paymentHandleToken": "BAru0JIKuktMcLsy"
}
},
"profile": {
"firstName": "ALBERTA",
"lastName": "BOBBETHCHARLESON",
"email": "accountholder0@example.com",
"dateOfBirth": {
"day": "23",
"month": "12",
"year": "1990"
},
"phone": 1234567890
},
"billingDetails": {
"nickName": "Home",
"street": "Queen Street West",
"street2": "Queen Street",
"city": "Imphal",
"state": "NY",
"country": "US",
"zip": "14236"
},
"merchantDescriptor": {
"dynamicDescriptor": "OnlineStore",
"phone": "12345678"
},
"returnLinks": [
{
"rel": "default",
"href": "http://www.amazon.ca"
},
{
"rel": "on_failed",
"href": "http://www.costco.ca"
},
{
"rel": "on_cancelled",
"href": "http://www.bestbuy.ca"
}
]
}
Payment Handle Response Example
{
"id": "cf005f03-8c31-4afb-884b-20ce9cb10190",
"paymentType": "PAYSAFECASH",
"paymentHandleToken": "PHtxnH0z99GXgc0Z",
"merchantRefNum": "ba4d021c-af45-4a64-b38a-c08f231e3825",
"currencyCode": "USD",
"txnTime": "2022-05-27T11:49:01Z",
"billingDetails": {
"street": "100 Queen",
"street2": "Unit 201",
"city": "New York",
"zip": "M5H 2N2",
"country": "US"
},
"customerIp": "172.0.0.1",
"status": "INITIATED",
"links": [
{
"rel": "redirect_payment",
"href": "https://api.test.paysafe.com/alternatepayments/v1/redirect?accountId=1002453740&paymentHandleId=cf005f03-8c31-4afb-884b-20ce9cb10190&token=eyJhbGciOiJIUzI1NiJ9.eyJhY2QiOiIxMDAyNDUzNzQwIiwicHlkIjoiY2YwMDVmMDMtOGMzMS00YWZiLTg4NGItMjBjZTljYjEwMTkwIiwiZXhwIjoxNjUzNjUzOTQxfQ.NO-FSBVgbI8L5fGR5o9RI-Z5DhckyRmEFOGJMsRZuiU"
}
],
"liveMode": false,
"simulator": "EXTERNAL",
"usage": "SINGLE_USE",
"action": "REDIRECT",
"executionMode": "SYNCHRONOUS",
"amount": 1000,
"merchantDescriptor": {
"dynamicDescriptor": "Test Paysafe",
"phone": "12345678"
},
"timeToLiveSeconds": 899,
"gatewayResponse": {
"processor": "SKRILL_QCO",
"sid": "a7f3fbc00a31bf85f82a0fd10df7979c"
},
"returnLinks": [
{
"rel": "default",
"href": "https://usgaminggamblig.com/payment/default"
},
{
"rel": "on_completed",
"href": "https://codepen.io/warrendunlop/full/YmVKzm"
},
{
"rel": "on_cancelled",
"href": "https://usgaminggamblig.com/payment/return/failed"
}
],
"transactionType": "PAYMENT",
"gatewayReconciliationId": "a5dbbd41-56da-4770-9e61-d2c1cda514eb",
"updatedTime": "2022-05-27T11:49:01Z",
"statusTime": "2022-05-27T11:49:01Z",
"paysafecash": {
"consumerId": "parag.p@test.com"
},
"profile": {
"firstName": "Parag",
"lastName": "P"
}
}
Payment Request Example
{
"merchantRefNum": "1644905922",
"amount": "100",
"currencyCode": "USD",
"dupCheck": true,
"settleWithAuth": true,
"paymentHandleToken": "PHD7rsXBgzRbllak",
"customerIp": "172.0.0.1",
"description": "Magazine subscription"
}
Payment Response Example
{
"id": "42da1422-1575-4c35-a36e-b9afd9c6abbe",
"paymentType": "MAZOOMA",
"paymentHandleToken": "PHD7rsXBgzRbllak",
"merchantRefNum": "1644905916",
"currencyCode": "USD",
"settleWithAuth": true,
"dupCheck": true,
"txnTime": "2022-02-15T06:17:38Z",
"billingDetails": {
"street1": "Queen Street West",
"street2": "Queen Street",
"city": "Imphal",
"zip": "14236",
"state": "NY",
"country": "US"
},
"status": "COMPLETED",
"gatewayReconciliationId": "d4474b2c-3ad5-4d2c-bf28-79d0259e6055",
"amount": 100,
"consumerIp": "172.0.0.1",
"liveMode": false,
"simulator": "EXTERNAL",
"updatedTime": "2022-02-15T06:18:37Z",
"statusTime": "2022-02-15T06:18:37Z",
"gatewayResponse": {
"orderId": "305887918",
"errCode": "0",
"id": "d4474b2c-3ad5-4d2c-bf28-79d0259e6055",
"internalRequestId": "394715428",
"processor": "MAZOOMA",
"status": "SUCCESS"
},
"availableToSettle": 0,
"profile": {
"firstName": "ALBERTA",
"lastName": "BOBBETHCHARLESON",
"email": "accountholder0@example.com",
"dateOfBirth": {
"day": 23,
"month": 12,
"year": 1990
},
"phone": "1234567890"
},
"settlements": {
"amount": 100,
"txnTime": "2022-02-15T06:17:38.000+0000",
"merchantRefNum": "1644905916",
"id": "42da1422-1575-4c35-a36e-b9afd9c6abbe",
"status": "COMPLETED"
}
}
Withdrawal
Payment Handle Request Example with bankToken
{
"merchantRefNum": "mer_ref_1644906040",
"transactionType": "STANDALONE_CREDIT",
"paymentType": "MAZOOMA",
"amount": 100,
"currencyCode": "USD",
"customerIp": "172.0.0.1",
"mazooma": {
"consumerId": "PP_100222",
"ach": {
"paymentHandleToken": "BAFtcP4i8r0udbEK"
}
},
"profile": {
"firstName": "ALBERTA",
"lastName": "BOBBETHCHARLESON",
"email": "accountholder0@example.com",
"dateOfBirth": {
"day": "23",
"month": "12",
"year": "1990"
},
"phone": 1234567890
},
"billingDetails": {
"street1": "Queen Street West",
"street2": "Queen Street",
"city": "Imphal",
"state": "NY",
"country": "US",
"zip": "14236"
},
"merchantDescriptor": {
"dynamicDescriptor": "OnlineStore"
},
"returnLinks": [
{
"rel": "default",
"href": "http://www.amazon.ca"
},
{
"rel": "on_failed",
"href": "http://www.costco.ca"
},
{
"rel": "on_cancelled",
"href": "http://www.bestbuy.ca"
}
]
}
Payment Handle Response Example
{
"id": "5c71dce8-61ed-4672-83ae-878293a17c71",
"paymentType": "MAZOOMA",
"paymentHandleToken": "PHWKPdpJr8g7lMwi",
"merchantRefNum": "mer_ref_1644906067",
"currencyCode": "USD",
"txnTime": "2022-02-15T06:21:07Z",
"billingDetails": {
"street": "Queen Street West",
"street2": "Queen Street",
"city": "Imphal",
"zip": "14236",
"state": "NY",
"country": "US"
},
"customerIp": "172.0.0.1",
"status": "PAYABLE",
"liveMode": false,
"simulator": "EXTERNAL",
"action": "NONE",
"amount": 100,
"merchantDescriptor": {
"dynamicDescriptor": "OnlineStore"
},
"timeToLiveSeconds": 899,
"gatewayResponse": {
"processor": "MAZOOMA"
},
"returnLinks": [
{
"rel": "on_failed",
"href": "http://www.costco.ca"
},
{
"rel": "on_cancelled",
"href": "http://www.bestbuy.ca"
},
{
"rel": "default",
"href": "http://www.amazon.ca"
}
],
"transactionType": "STANDALONE_CREDIT",
"updatedTime": "2022-02-15T06:21:08Z",
"statusTime": "2022-02-15T06:21:08Z",
"mazooma": {
"consumerId": "PP_100222",
"ach": {
"paymentHandleToken": "BAFtcP4i8r0udbEK"
}
},
"_links": {
"self": {
"href": "http://paysafe-psp-alternatepayments-mazooma.mtl-qa.svc.cluster.local/v1/accounts/9becfecc-e69a-4e38-87dc-36e1d5efbcd1/paymenttypes/mazooma/paymenthandles/b61baa59-0127-4baf-9183-ecf66f150e9b"
}
},
"profile": {
"firstName": "ALBERTA",
"lastName": "BOBBETHCHARLESON",
"email": "accountholder0@example.com",
"dateOfBirth": {
"day": 23,
"month": 12,
"year": 1990
},
"phone": "1234567890"
}
}
Withdrawal Request Example
{
"merchantRefNum": "mer_ref_1644906067",
"amount": "100",
"currencyCode": "USD",
"dupCheck": true,
"settleWithAuth": true,
"paymentHandleToken": "PHWKPdpJr8g7lMwi",
"customerIp": "172.0.0.1",
"description": "Magazine subscription"
}
Withdrawal Response Example
{
"id": "fa19cd7c-2a41-4d42-adc2-5c9115d7d191",
"paymentType": "MAZOOMA",
"paymentHandleToken": "PHWKPdpJr8g7lMwi",
"merchantRefNum": "mer_ref_1644906067",
"currencyCode": "USD",
"dupCheck": true,
"txnTime": "2022-02-15T06:21:54Z",
"billingDetails": {
"street1": "Queen Street West",
"street2": "Queen Street",
"city": "Imphal",
"zip": "14236",
"state": "NY",
"country": "US"
},
"customerIp": "172.0.0.1",
"status": "COMPLETED",
"gatewayReconciliationId": "49514d38-3741-43f2-94d9-24bfb7b57170",
"amount": 100,
"returnLinks": [
{
"rel": "default",
"href": "http://www.amazon.ca"
},
{
"rel": "on_failed",
"href": "http://www.costco.ca"
},
{
"rel": "on_cancelled",
"href": "http://www.bestbuy.ca"
}
],
"liveMode": false,
"simulator": "EXTERNAL",
"updatedTime": "2022-02-15T06:21:58Z",
"statusTime": "2022-02-15T06:21:58Z",
"gatewayResponse": {
"transactionStatus": "APPROVED",
"errCode": "0",
"id": "49514d38-3741-43f2-94d9-24bfb7b57170",
"externalTransactionId": "7110000000148650",
"processor": "MAZOOMA",
"transactionId": "711000000008001548",
"status": "SUCCESS"
},
"mazooma": {
"consumerId": "PP_100222",
"ach": {
"paymentHandleToken": "BAFtcP4i8r0udbEK"
}
},
"profile": {
"firstName": "ALBERTA",
"lastName": "BOBBETHCHARLESON",
"email": "accountholder0@example.com",
"dateOfBirth": {
"day": 23,
"month": 12,
"year": 1990
},
"phone": "1234567890"
}
}
Appendix
Payment
After the /paymenthandles call is made, Mazooma checks the available balance in user account. If funds are available then Merchant receives the Payment Handle "PAYABLE" webhook; if funds are not available then Merchant receives Payment Handle "FAILED" webhook.
At Mazooma end, Saved Banks are referred as UPO (User Payment Option). In Paysafe APIs, we refer Saved Bank or UPO as bankToken (mazooma.achBankAccounts.paymentHandleToken).
The actual debit to customer account happens at a later stage.
Customer Account Debit
Mazooma tries to debit customer account on T+1 day.
If funds are available in the user account, then Mazooma will debit the users account. Merchant will not receive any webhook.
If this attempt fails due to "Insufficient Funds" then you will receive 2 webhooks; "Return" webhook followed by "Representment" webhook
If this attempt fails due to error/issue other than "Insufficient Funds" then you will receive 1 webhooks; "Return" webhook
Representment
Representment is an attempt to charge (debit) the customer’s bank account if Mazooma is not able to debit Customer account on T+1 day.
There will be maximum two Representment attempts.
Representment 1: Mazooma will attempt to debit the user account on T+3 day from the transaction date.
If funds are available in the user account then Mazooma will debit the users account. Merchant will not receive any webhook.
If this attempt fails then you will receive 2 webhooks; "Return" webhook followed by "Representment" webhook
Representment 2: Attempt to charge (debit) the customer’s bank account if 1st Representment fails. Mazooma will re-attempt to debit the user account either on 15th of the month or last day of the month, whichever is earliest.
- If funds are available in the user account then Mazooma will debit the users account. Merchant will not receive any webhook.
- If this attempt fails then "Return" webhook will be sent. There will be No "Representment" webhook.
If transaction is Declined by Mazooma (Since Representment has failed) then you will receive a "Return" webhook.
Webhooks
At Mazooma end, Saved Banks are referred as UPO (User Payment Option)
Payments without UPO
1. User created PaymentHandle and redirected to Mazooma and completed Payment.
- Paymenthandle= PAYABLE
2. User created PaymentHandle and redirected to Mazooma and completed Payment and then Merchant initiated Payments call, transaction is successful.
- Paymenthandle=COMPLETED, Payment=COMPLETED
3. User created PaymentHandle and did not redirect to Mazooma.
- Paymenthandle=INITIATED
4. User created PaymentHandle and redirected to Mazooma
- Paymenthandle=PROCESSING
5. User created PaymentHandle and redirected to Mazooma, but transaction authorization failed.
- Paymenthandle=FAILED
6. User created PaymentHandle and redirected to Mazooma, but error occurred while redirecting to PSP link.
- Paymenthandle=FAILED
Payment with UPO
- User created PaymentHandle with valid UPO details and redirected to Mazooma to complete the Payment.
- Paymenthandle= PAYABLE
- User created PaymentHandle with valid UPO details and redirected to Mazooma to complete Payment, and then Merchant initiated Payments call, transaction is successful.
- Paymenthandle=COMPLETED, Payment=COMPLETED
Withdrawal (StandaloneCredit)
- User created SCT_Paymenthandle and Merchant didn't initiate Standalonecredits call
- Paymenthandle=PAYABLE
- User created Paymenthandle and Merchant completed Standalonecredits call
- Paymenthandle=COMPLETED, Standalonecredits=COMPLETED
- User created Paymenthandle and Merchant initiated Standalonecredits call, transaction went into "PROCESSING"
- Paymenthandle=COMPLETED, Standalonecredits=PROCESSING
- Merchant will receive webhook Standalonecredit=COMPLETED once status changes from PROCESSING to COMPLETED
- User created Paymenthandle and Merchant initiated Stnadalonecredits call with invalid transaction details.
- Paymenthandle=COMPLETED, Standalonecredits=ERROR)
Testing Instructions
This section explains how to test scenarios to get the expected results with internal simulator.
Payment
Below, amount based simulations are used to COMPLETE/FAIL the Payment transactions with internal simulator. We need to send amount value in the request to get the respected result.
- Status will change after time limit. Example for amount 101 it will wait for 1 minute to APPROVED then update the status to DECLINED in 3 Minutes
| Amount(dollars) | Real Scenario | Simulation Case | Webhooks |
|---|---|---|---|
| 101 | There is sufficient balance in user account when transaction is initiated. Mazooma approved the transaction.
Mazooma tried to debit user account on T+1 day but it failed due to reason other than "Insufficient Balance"
|
| Paymenthandle "PAYABLE" within 60 Seconds -> "RETURN" webhook after 180 seconds |
| 102 | There is sufficient balance in user account when transaction is initiated. Mazooma approved the transaction.
Mazooma tried to debit user account on T+1 day but it failed due to reason "Insufficient Balance". This qualifies for REPRESENTMENT.
|
| Paymenthandle "PAYABLE" within 60 Seconds -> "RETURN" webhook & "REPRESENTMENT" webhook after 120 seconds |
| 103 | There is sufficient balance in user account when transaction is initiated. Mazooma approved the transaction.
Mazooma tried to debit user account on T+1 day but it failed due to reason "Insufficient Balance". This qualifies for REPRESENTMENT.
Mazooma tried to debit user account on T+3 day but it failed due to reason other than "Insufficient Balance". This does not qualify for REPRESENTMENT.
|
| Paymenthandle "PAYABLE" within 60 Seconds -> "RETURN" webhook & "REPRESENTMENT" webhook after 120 seconds ->"RETURN" webhook after 180 seconds |
| 104 | There is sufficient balance in user account when transaction is initiated. Mazooma approved the transaction.
Mazooma tried to debit user account on T+1 day but it failed due to reason "Insufficient Balance". This qualifies for REPRESENTMENT
Mazooma tried to debit user account on T+3 day but it failed due to reason "Insufficient Balance". This qualifies for REPRESENTMENT
|
| Paymenthandle "PAYABLE" within 60 Seconds -> "RETURN" webhook & "REPRESENTMENT" webhook after 120 seconds ->"RETURN" webhook & "REPRESENTMENT" webhook after 180 seconds |
| 105 | There is sufficient balance in user account when transaction is initiated. Mazooma approved the transaction.
Mazooma tried to debit user account on T+1 day but it failed due to reason "Insufficient Balance". This qualifies for REPRESENTMENT
Mazooma tried to debit user account on T+3 day but it failed due to reason "Insufficient Balance". This qualifies for REPRESENTMENT
Mazooma tried to debit user account on 15th or Last day of the month but debit failed
|
| Paymenthandle "PAYABLE" within 60 Seconds -> "RETURN" webhook & "REPRESENTMENT" webhook after 120 seconds ->"RETURN" webhook & "REPRESENTMENT" webhook after 120 seconds ->"RETURN" webhook after 180 seconds |
Standalone Credits
Below, amount based simulations are used to COMPLETE/FAIL/ERROR the transactions with internal simulator.
| Amount(dollars) | Status | DMN Notification | Time Limit |
|---|---|---|---|
| 101 | COMPLETED | APPROVED -> DECLINED | APPROVED After 60 Seconds - DECLINED After 3 Minutes |
Error Codes
API Response Codes
| Mazooma Error Code | Reason | Paysafe Http Status | Paysafe Error Code | Paysafe Error Message | Paysafe Error Details | Paysafe Status | Status Reason | Remarks |
|---|---|---|---|---|---|---|---|---|
| 1000 | General Error | 502 | 1001 | External gateway error | An external gateway error occurred. | ERROR | NA | |
| 1010 | Invalid user token | 400 | 5068 | INVALID_FIELD | Either you submitted a request that is missing a mandatory field or the value of a field does not match the format expected. | ERROR | NA | |
| 1011 | Missing or invalid UserPaymentOption data | 400 | 5068 | INVALID_FIELD | Either you submitted a request that is missing a mandatory field or the value of a field does not match the format expected. | ERROR | NA | |
| 1021 | Invalid timestamp | 502 | 1001 | External gateway error | An external gateway error occurred. | ERROR | NA | |
| 1023 | User payment option is not enabled | 400 | 5068 | INVALID_FIELD | Either you submitted a request that is missing a mandatory field or the value of a field does not match the format expected. | ERROR | NA | mazooma.ach.paymentHandleToken is not valid |
| 1024 | UPO limit per user exceeded | 502 | 1001 | External gateway error | An external gateway error occurred. | ERROR | NA | |
| 1038 | Communication error | 502 | 1001 | External gateway error | An external gateway error occurred. | ERROR | NA | |
| 1040 | Invalid or missing amount | 400 | 5068 | INVALID_FIELD | Either you submitted a request that is missing a mandatory field or the value of a field does not match the format expected. | ERROR | NA | |
| 1041 | Invalid or missing amount currency | 400 | 5068 | INVALID_FIELD | Either you submitted a request that is missing a mandatory field or the value of a field does not match the format expected. | ERROR | NA | |
| 1064 | Invalid session token. There can be only one order per session token. | 502 | 1001 | External gateway error | An external gateway error occurred. | ERROR | NA | |
| 1065 | Invalid token | 502 | 1001 | External gateway error | An external gateway error occurred. | ERROR | NA | |
| 1066 | Invalid Request | 502 | 1001 | An external gateway error occurred. | ERROR | NA | ||
| 1067 | Invalid or missing transaction type | 502 | 1001 | An external gateway error occurred. | ERROR | NA | ||
| 1068 | Payment method is not enabled | ACCOUNT_NOT_ACTIVATED | ||||||
| 1069 | Session expired | 502 | 1001 | External gateway error | An external gateway error occurred. | ERROR | NA | |
| 1074 | The user payment option is expired. | 502 | 1001 | External gateway error | An external gateway error occurred. | ERROR | NA | |
| 1090 | UPO is not in valid status. Valid statuses are ENABLED, SUSPENDED and FROZEN. | 501 | 1001 | External gateway error | An external gateway error occurred. | ERROR | NA | |
| 1109 | Invalid email | 400 | 5068 | INVALID_FIELD | Either you submitted a request that is missing a mandatory field or the value of a field does not match the format expected. | ERROR | NA | |
| 1113 | {0}The state is not from the country | 400 | 5068 | INVALID_FIELD | Either you submitted a request that is missing a mandatory field or the value of a field does not match the format expected. | ERROR | NA | |
| 1121 | Merchant not verified | 400 | 5017 | Account disabled | The account provided is disabled. | ERROR | NA | |
| 1122 | Merchant site disabled | 400 | 5017 | Account disabled | The account provided is disabled. | ERROR | NA | |
| 1125 | UPO Payment method is not supported by this method. | 502 | 1001 | External gateway error | An external gateway error occurred. | ERROR | NA | |
| 2006 | Currency conversion is not supported. | 502 | 1001 | External gateway error | An external gateway error occurred. | ERROR | NA | |
| 9065 | The currency is not supported by the payment method | 502 | 1001 | External gateway error | An external gateway error occurred. | ERROR | NA | |
| 9066 | Exchange rate not available | 502 | 1001 | External gateway error | An external gateway error occurred. | ERROR | NA | |
| 9072 | Payment is still in progress | 502 | 1001 | External gateway error | An external gateway error occurred. | ERROR | NA | |
| 9073 | Invalid or missing country and currency | 502 | 1001 | External gateway error | An external gateway error occurred. | ERROR | NA | |
| 9083 | Invalid or missing clientRequestId. | 502 | 1001 | External gateway error | An external gateway error occurred. | ERROR | NA | |
| 9084 | Provided clientRequestId is not associated with a payout transaction. | 502 | 1001 | External gateway error | An external gateway error occurred. | ERROR | NA | |
| 9093 | Account not found. | 502 | 1001 | External gateway error | An external gateway error occurred. | ERROR | NA | |
| 9095 | Add Bank Account failed. | 502 | 1001 | External gateway error | An external gateway error occurred. | ERROR | NA | |
| 9096 | Cannot fund user account at this time. | 502 | 1001 | External gateway error | An external gateway error occurred. | ERROR | NA | |
| For all other error codes | 502 | 1001 | External gateway error | An external gateway error occurred. | ERROR | NA |