mazoomapaymentapi-apiary.apib

FORMAT: 1A
HOST: https://api2.test.paysafe.com/

# Mazooma Payments API

Mazooma is a popular Automated Clearing House (ACH) based payment method in the United States. It is currently being developed for US iGaming merchants with both deposits and withdrawals/SCT.

+ All Mazooma transactions will be processed in US dollars.
+ Transactions through a US IP address will be accepted; transactions involving any other IP address will be rejected.
+ It makes use of the ACH system.
+ It is a redirect payment method

# Release Notes

| Version   | Date                  | Details |
|---        |---                    |---      |
| v1        |29th Jan 2022          | Initial Draft|

# Overview

Connect your application directly with our payment engine to process a full suite of methods that are REST-based – designed to be easy to understand and use. Ultimate control puts you in the driver’s seat.
* Choose an efficient, lightweight, and fast integration method to access our API.
* Implement a wide variety of REST-based API requests – including Purchases, Refunds, and Void  Authorizations.
* Obtain output in JSON format – it’s easy to parse in a large variety of Web and mobile applications.
* Use any language or platform to make requests through standard HTTP protocols.

<a name="apikey" title="Authentication"></a>
# Authentication

In order for you to use the Paysafe REST API, Paysafe must first set you up on their system
and provide you with an API key. Your API key looks something like this:

 * Key Username – MerchantXYZ
 * Key Password – B-tst1-0-51ed39e4-312d02345d3f123120881dff9bb4020a89e8ac44cdfdcecd702151182fdc952272661d290ab2e5849e31bb03deede7e

Note that this is not the same as your Merchant Back Office username and password.

The case-sensitive API key is sent using HTTP Basic Authentication. To use HTTP Basic Authentication, you must send the API key credentials using the Authorization header with every request. The Authorization header is constructed as follows:

 1. The Key Username and Key Password are combined into a string separated by a colon, e.g.,“Key Username:Key Password”.
 2. The resulting string literal is then encoded using Base64.
 3. The authorization method and a space (i.e., “Basic”) are then put before the encoded string.

For example, using the Key Username and Password examples above, the header is formed as follows:

``Authorization: Basic
TWVyY2hhbnRYWVo6Qi10c3QxLTAtNTFlZDM5ZTQtMzEyZDAyMzQ1ZDNmMTIzMTIwODgxZGZmOWJiNDAyMGE4OWU4YWM0NGNkZmRjZWNkNzAyMTUxMTgyZmRjOTU yMjcyNjYxZDI5MGFiMmU1ODQ5ZTMxYmIwM2RlZWRlN2U=``

For additional details, please refer to [http://en.wikipedia.org/wiki/Basic_access_authentication](http://en.wikipedia.org/wiki/Basic_access_authentication).

**Note:** Your Production API key will be different from your Test API key. Contact your account manager for details. You must keep your API keys safe and ensure that it is used appropriately for your needs.

# URLs

##  Test URL
In order to test your integration with Paysafe, use the following Test URL:

`https://api.test.paysafe.com`

For example:

`https://api.test.paysafe.com/getSessionToken}`

## Production URL
In order to process live requests with Paysafe, use the following Production URL:

`https://api.paysafe.com`

For example:

`https://api.paysafe.com/getSessionToken}`

# Mazooma Payments Flow

After the /payments call is made successfully, Mazooma validates the available balance from user accounts. Here there can be only two scenarios either the funds are available or funds are not available. In case funds are not available DMN returns "DECLINE" ; if funds are available DMN returns "Accepted" on respective urls specified in the call. 

**Note:** Untill here Mazooma doesn't debit the users account. The actual transfer happens in subsequent steps

**Concept of Representment:** If the funds were initially available, Mazooma will attempt to transfer the funds. Here there are two scenarios:

**Scenario 1: Transfer is successful → Funds are available to debit the user account.**

In this scenario, the funds are debited from the users account and no further notification is received

**Note:** For successful transactions, if no further notification is received for 5 business days then the transaction can be marked successful. In other words we should wait for 5 business days to mark a transaction success even if DMN returns " APPROVED" in the first call

**Scenario2: Transfer is not successful → There can be multiple reason for the unsuccessful transaction.**

(i) For any reason except for 'insufficient funds' the transaction is marked "DECLINED" and a DMN notification update with "status=DECLINE" will be received.

(ii) In case of insufficient funds: If the funds were initially available but for some reason are not currently available, Mazooma doesn't straight away rejects the transactions. Rather it waits upto 10 business days to represent the transaction and thus increase the success rate. At this point the process of Representment kicks in. This means starting now, Mazooma will attempt to debit the user account within 3 business days. In the DMN notification received we will receive status="nextActionDate". With each representment Mazooma sends DMN notification with "status=update". This includes all information related to representment as to when the next represntment will be made. 

Mazooma attempts for Representment twice - 1st within 3 Business days ; In case this is unsuccessful Mazooma will re attempt debit either on 15th of the month or last day of the month, whichever is earliest.

If at the end of 2attempts, Mazooma is still not able to collect the amount a DMN notification with status=Decline will be sent. This will update the initial status from "APPROVED" to "DECLINE"

## Mazooma Deposit Payments Flow

![](https://raw.githubusercontent.com/SwathiBirlangi/Mazoomaimages/main/Mazooma%20-%20Deposit%20Flow.png)

## Mazooma Withdrawal Payments Flow

![](https://raw.githubusercontent.com/SwathiBirlangi/Mazoomaimages/main/Mazooma%20Withdraw%20Flow.png)

# Mazooma Payments - Deposits [/getSessionToken]
<a name="Mazoomapaymentsdeposits" title="Mazooma Payments Deposits"></a>

## Payments for New User (without UPO) [POST /getSessionToken]
<a name="paymentsfornewuser" title="Payments for New User"></a>

If its a first time user of Mazooma, we will not have a UPO (User Payment Option ID). This will be generated as a response to the /payments call. 

General Method→ /payments request is made → if Success → UPO is generated (which is saved for future payments) 

**Step 1: call /getSessionToken**

This is required to validate the merchant authentication details. This call returns the token that are required to be passed in subsequent calls

**Step 2: Call / payments:**

Make the /payments call to make payments for any kind (in our case Mazooma payments). This call require some mandatory fields. Please see fields below -

Authentication credentials – sessionToken, merchantId, merchantSiteId, checksum, timeStamp, and country and email (under billingAddress). This is the response we get in /sessionToken call
amount and currency
A payment option 
Additional Parameters

Additional Parameters for /payments call for Mazooma

|Parameter|Value|Mandatory|
|-----|-----|--------|
|paymentOption.alternativePaymentMethod.paymentMethod|apmgw_eCheckSelect |Y|
|userDetails.firstName | |Y |
|userDetails.lastName | |Y  |
|userDetails.address| |Y  |
|userDetails.city | |Y  |
|userDetails.state | |Y  |
|userDetails.zip | |Y  |
|userDetails.dateOfBirth | |Y  |

**Step 3: paymentOption.redirectURL**

If /payments request is created successfully, it returns redirect url. Thee user is redirected to his banking page where he can confirm his banking details from which account he wants to pay from 

**Step 4:  Mazooma Payment Flow (for detailed note refer Payment flow)**

After the user confirms the banking details, Mazooma checks the users bank account for balance. 

Scenario 1: Balance is not available → DMN (Direct Merchant Notification url) returns "Declined" and the journey ends

Scenario 2: Balance available→ DMN returns "Approved" and UPO (User Payment Option Id) is generated and returned

**Step 5: DMN Returned**

A DMN is returned on th eurl specified in request with the UPO ID which can be stored for further transactions.

+ Request (application/json)

{
    "merchantId": "427583496191624621",
    "merchantSiteId": "142033",
    "clientRequestId": "1C6CT7V1L",
    "timeStamp": "20191105081132",
    "checksum": "7e797f2270a1bffd2608a97ecc0fab550a61254f840b76e166aab9c487718b25"
}

+ Response 201 (application/json)

{
    "sessionToken": "2da9b9cd-573e-4055-a209-3ac2b855f9af",
    "internalRequestId": 222310158,
    "status": "SUCCESS",
    "errCode": 0,
    "reason": "",
    "merchantId": "427583496191624621",
    "merchantSiteId": "142033",
    "version": "1.0",
    "clientRequestId": "1C6CT7V1L"
}

# Payments for New User (with UPO) [/getSessionToken]

## Payments for New User (with UPO) [POST /getSessionToken]

If a user already exists we will always have a UPO available and hence these payments will always be using UPO. The user is prompted to select any of the already added bank account and once the user selects /getSessionToken call is made followed by /payments call with all the required fields. (refer all steps in payment without UPO except for **step 3**

+ Request (application/json)

{
  "sessionToken": "1be68338-e45e-4c81-b617-e1bfb94cae3e",
  "merchantId": "2502136204546424962",
  "merchantSiteId": "126006",
  "userTokenId": "2J6QZH3UF9E2",
  "clientRequestId": "2VXORP7A1",
  "clientUniqueId": "695701003",
  "currency": "USD",
  "amount": "1",
  "paymentOption": {
    "userPaymentOptionId": "8061731"
  },
  "billingAddress": {
    "firstName": "ALBERTA",
    "lastName": "BOBBETHCHARLESON",
    "email": "accountholder0@example.com",
    "phone": "1112223333",
    "dateOfBirth": "1944-09-24",
    "address": "2992 Cameron Road",
    "city": "Newark",
    "zip": "14236",
    "state": "NY",
    "country": "US",
    "language": "en"
  },
  "userDetails": {
    "firstName": "ALBERTA",
    "lastName": "BOBBETHCHARLESON",
    "email": "accountholder0@example.com",
    "phone": "1112223333",
    "dateOfBirth": "1944-09-24",
    "address": "2992 Cameron Road",
    "city": "Newark",
    "zip": "14236",
    "state": "NY",
    "country": "US",
    "language": "en"
  },
  "shippingAddress": {
    "firstName": "ALBERTA",
    "lastName": "BOBBETHCHARLESON",
    "email": "accountholder0@example.com",
    "phone": "1112223333",
    "dateOfBirth": "1944-09-24",
    "address": "2992 Cameron Road",
    "city": "Newark",
    "zip": "14236",
    "state": "NY",
    "country": "US",
    "language": "en"
  },
  "deviceDetails": {
    "deviceType": "DESKTOP",
    "deviceName": "iPhone 5s",
    "deviceOS": "iOS 10.2",
    "browser": "safari",
    "ipAddress": "192.168.2.38"
  },
  "urlDetails": {
    "successUrl": "[The URL the customer is directed to after a successful transaction]",
    "pendingUrl": "[The URL the customer is directed to when the transaction response is pending]",
    "failureUrl": "[The URL the customer is directed to after an unsuccessful transaction]",
    "notificationUrl": "[The URL to which DMNs are sent]"
  },
  "timeStamp": "20210820100801",
  "checksum": "232b8d91928e395db573e212549a519a"
}

+ Response 201 (application/json)

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


# Mazooma Payments - Withdrawals [/getSessionToken]
<a name="mazoomapaymentswithdrawals" title="Mazooma Payments Withdrawals"></a>

## Mazooma Payments - Withdrawals [POST /getSessionToken]

Mazooma Payouts work almost in the same manner like payments. We need to make /payouts call for payouts.

**Step 1: call /getSessionToken**

This is required to validate the merchant authentication details. This call returns the token that is required to be passed in subsequent calls

**Step 2: Call / payouts:**

Make the /payouts call to make payouts for any kind (in our case Mazooma payments). This call require some mandatory fields. Please see fields below -

sessionToken
UPO Id (userPaymentOption Id)

**Step 3: DMN Returned**

After a payout request is successfully created a DMN Notification is returned on the url specified in request with the result of the transaction like Status="SUCCESS" for successfull transactions

+ Request (application/json)

{
  "merchantId": "2502136204546424962",
  "merchantSiteId": "126006",
  "userTokenId": "CEBQK9OVSLJA",
  "clientUniqueId": "695701003",
  "clientRequestId": "W1Q3SBGE4",
  "currency": "USD",
  "amount": "35",
  "userPaymentOption": {
    "userPaymentOptionId": "8054521"
  },
  "deviceDetails": {
    "deviceType": "TABLET",
    "deviceName": "iPad",
    "deviceOS": "iOS U",
    "browser": "safari U",
    "ipAddress": "FE80::0202:B3FF:FE1E:8329"
  },
  "urlDetails": {
    "notificationUrl": "http://srv-bsf-devppptrunk.gw-4u.com/ppptest/NotifyMerchantTest"
  },
  "timeStamp": "20210820100854",
  "checksum": "337b909d70a83478eb1cea861f1795a4"
}

+ Response 201 (application/json)

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