Mazooma

Mazooma is a bill payment option in the US that processes payments 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:

  1. Payments - Used to transfer money from customer's bank account to merchant account. Post successful payments, merchant credits the customer's wallet.
  2. Withdrawal - Used to transfer money from merchant account to customer's bank account.

Typical Scenarios

Payments

When you want to process a payment request, 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 Payment call

User with bankToken

  1. Create a Payment Handle with the transactionType parameter set to PAYMENT and the paymentType parameter set to MAZOOMA.
    1. POST: paymenthub/v1/paymenthandles
  2. Since the customer has to bankToken:
    • Pass the consumerid along with bankToken in the mazooma object.
  3. You will receive "paymentHandleToken" in the response. The response should have "status" as PAYABLE.
  4. 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:
    1. POST: paymenthub/v1/payments

User without bankToken

  1. Create a Payment Handle with the transactionType parameter set to PAYMENT and the paymentType parameter set to MAZOOMA.
    1. Post : paymenthub/v1/paymenthandles
  2. 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
  3. Redirect the customer to the Plaid redirect URL.
    1. 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
      1. On redirection page, customer selects the bank, provides credentials, and processes the transaction.
  4. 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:
    1. Post : paymenthub/v1/payments
  5. You will receive bankToken (mazooma.achBankAccounts.paymentHandleToken) in in the response. The response should have "status" as COMPLETED
    1. The bankToken can be used in the "User with bankToken" flow

APIs to use:Payment Handles for Verification + Verification + Payment Handles for Payments + Payments

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

  1. Create a Payment Handle with the transactionType parameter set to STANDALONE_CREDIT and the paymentType parameter set to MAZOOMA.
    1. Post : paymenthub/v1/paymenthandles
  2. Since the customer has to bankToken:
    • Pass the consumerid along with bankToken in the mazooma object.
  3. You will receive "paymentHandleToken" in the response. The response should have "status" as PAYABLE.
  4. 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:
    1. Post : paymenthub/v1/standalonecredits

APIs to use:Payment Handles for Verification + Verification + Payment Handles for Standalone Credits+ Standalone Credit

Delete a Bank Account

Make a delete bank account using Http method DELETE. Below are the details:

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 the all payment Handle request.

"mazooma": {
        "consumerId": "PP_100222"
    }

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

Payments

Payments 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"
    }
  ]
}

Payments 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"
    }
  ]
}

Payments 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"
    }
}

To know more about each parameter, you can visit Payment Handles

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"
    }
}

To know more about each parameter, you can visit Payments

Withdrawal

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"
    }
  ]
}

Withdrawal 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"
    }
}

To know more about each parameter, you can visit Payment Handles

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"
    }
}

To know more about each parameter, you can visit Standalone Credits

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

  1. User created PaymentHandle with valid UPO details and redirected to Mazooma to complete the Payment.
    • Paymenthandle= PAYABLE
  2. 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)

  1. User created SCT_Paymenthandle and Merchant didn't initiate Standalonecredits call
    • Paymenthandle=PAYABLE
  2. User created Paymenthandle and Merchant completed Standalonecredits call
    • Paymenthandle=COMPLETED, Standalonecredits=COMPLETED
  3. 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
  4. 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.

Amount(dollars) Real Scenario Simulation Case Webhooks
101

There is sufficient balance in user account when transaction is initiated. Mazooma approved the transaction.

  • You will receive paymenthandle "PAYABLE" webhook

Mazooma tried to debit user account on T+1 day but it failed due to reason other than "Insufficient Balance"

  • You will receive "RETURN" webhook
  • You will receive paymenthandle "PAYABLE" webhook within 60 seconds.
  • You will receive "RETURN" webhook after 180 seconds.
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.

  • You will receive paymenthandle "PAYABLE" webhook.

Mazooma tried to debit user account on T+1 day but it failed due to reason "Insufficient Balance". This qualifies for REPRESENTMENT.

  • You will receive "RETURN" webhook and "REPRESENTMENT" webhook
  • You will receive paymenthandle "PAYABLE" webhook after 60 seconds.
  • You will receive "RETURN" webhook and "REPRESENTMENT" webhook after 120 seconds.
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.

  • You will receive paymenthandle "PAYABLE" webhook

Mazooma tried to debit user account on T+1 day but it failed due to reason "Insufficient Balance". This qualifies for REPRESENTMENT.

  • You will receive "RETURN" webhook and "REPRESENTMENT" webhook

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.

  • You will receive "RETURN" webhook
  • You will receive paymenthandle "PAYABLE" webhook within 60 seconds.
  • You will receive "RETURN" webhook and "REPRESENTMENT" webhook after 120 seconds.
  • You will receive "RETURN" webhook after 180 seconds.
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.

  • You will receive paymenthandle "PAYABLE" webhook

Mazooma tried to debit user account on T+1 day but it failed due to reason "Insufficient Balance". This qualifies for REPRESENTMENT

  • You will receive "RETURN" webhook and "REPRESENTMENT" webhook

Mazooma tried to debit user account on T+3 day but it failed due to reason "Insufficient Balance". This qualifies for REPRESENTMENT

  • You will receive "RETURN" webhook and "REPRESENTMENT" webhook
  • You will receive paymenthandle "PAYABLE" webhook within 60 seconds.
  • You will receive "RETURN" webhook and "REPRESENTMENT" webhook after 120 seconds.
  • You will receive "RETURN" webhook and "REPRESENTMENT" webhook after 3 minutes.
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.

  • You will receive paymenthandle "PAYABLE" webhook

Mazooma tried to debit user account on T+1 day but it failed due to reason "Insufficient Balance". This qualifies for REPRESENTMENT

  • You will receive "RETURN" webhook and "REPRESENTMENT" webhook

Mazooma tried to debit user account on T+3 day but it failed due to reason "Insufficient Balance". This qualifies for REPRESENTMENT

  • You will receive "RETURN" webhook and "REPRESENTMENT" webhook

Mazooma tried to debit user account on 15th or Last day of the month but debit failed

  • You will receive "RETURN" webhook
  • You will receive paymenthandle "PAYABLE" webhook within 60 seconds.
  • You will receive "RETURN" webhook and "REPRESENTMENT" webhook after 120 seconds.
  • You will receive "RETURN" webhook and "REPRESENTMENT" webhook after 3 minutes.
  • You will receive "RETURN" webhook
Paymenthandle "PAYABLE" within 60 Seconds -> "RETURN" webhook & "REPRESENTMENT" webhook after 120 seconds ->"RETURN" webhook & "REPRESENTMENT" webhook after 120 seconds ->"RETURN" webhook after 180 seconds
  • 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

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

Did you find this page useful?