How to create a new payout using MassPay

Before you start

• MassPay account created
• MassPay API credentials available
• Postman or similar software with the same functionality

📘

Optional: Idempotency-Key

The API supports idempotency for safely retrying requests without accidentally performing the same operation twice. This is useful when an API call is disrupted in transit and you do not receive a response. For example, if a request to create a charge does not respond due to a network connection error, you can retry the request with the same idempotency key to guarantee that no more than one payout is created.

Step one: Check Available Balance

To ensure that you have sufficient funds to make a payout transaction, you should first check your available balances in your account. API will return the current available balances in your account, as well as the currency in which it is denominated.

🚧

Insufficient funds

If your balance is insufficient, you may need to add funds to your account before proceeding with the payout transaction.

1. Open your Postman and import OpenApi specification with GET /account/balance.

📘

You can find our OpenApi specification here.

2. Fill the environment and version to the Header and Bearer access-token as Authorization method.

Header

curl -X GET https://{environment}.masspay.io/{VERSION}/account/balance \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer {access-token}'

3. Call the REST API. Your response should look like this:

[
  {
    "token": "8bb3693f-2f98-43dd-a990-615b6a21596d",
    "balance": 100.5,
    "currency_code": "USD"
  }
]

👍

200-OK Response?

As a response, you will get all the balances of your account. Enough balance? So we can proceed to the next step.

Step two: Create User

Creating a user is a necessary step before being able to make payouts. With MassPay's REST API, creating a user is a quick and easy process that can be completed with just a few lines of code. Once the user is created, they can be used for future payouts without needing to repeat this step.

1. Open your Postman and import OpenApi specification with POST /user.

📘

You can find our OpenApi specification here.

2. Fill the environment and version to the Header and Bearer access-token as Authorization method.

Header

3. Fill the Body parameters according to your customers provided information.
4. Call the REST API. Your response should look like this:

{
  "user_token": "usr_ba4275f2-bae1-488d-9d6f-20af1cd83574",
  "status": "ACTIVE",
  "created_on": "2019-07-07T23:03:05",
  "internal_user_id": "4324-rOzk",
  "address1": "2000 main st",
  "address2": "apt D",
  "city": "Santa Monica",
  "state_province": "CA",
  "postal_code": "90405",
  "country": "USA",
  "first_name": "John",
  "middle_name": "",
  "last_name": "Doe",
  "email": "[email protected]",
  "language": "en",
  "mobile_number": "16502000226",
  "business_name": "ABC Company",
  "timezone": "America/Los_Angeles",
  "date_of_birth": "1975-03-24",
  "metadata": {"group_id":541}
}

👍

200-OK Response?

As a response, you will get all the information about the user you just created. So we can proceed to the next step.

Step three: Get destination token

To initiate a payout transaction, you need to provide the destination token for where the money will be sent. You can use the MassPay API's GET "Country Services" endpoint to retrieve the destination token for a given country. This endpoint takes the country code as an input parameter and returns the corresponding destination token.

1. Open your Postman and import OpenApi specification with GET /country/{country_code}/cheapest.

📘

You can find our OpenApi specification here.

2. Fill environment, version and country_code to the Header and Bearer access-token as Authorization method.

Header

👍

Good to know...

You can narrow your search using our optional parameters such as e.g.: source_currency, wallet_token, limit, ...

3. Call the REST API. Your response should look like this:

{
  "companies": [
    {
      "company_logo": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAMgAAADICAIAAAAiOjnJAAAABGdBTUEAALGP...",
      "services": [
        {
          "country_code": "MEX",
          "delivery_type": "CASH_PICKUP",
          "payers": [
            {
              "destination_token": "dest_d2138fd0-00be-45a8-985f-4f5bde500962",
              "payer_logo": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAMgAAADICAIAAAAiOjnJAAAABGdBTUEAALGP...",
              "payer_name": "Elektra",
              "exchange_rate": [
                {
                  "currency_symbol": "MXN",
                  "exchange_rate": 18.37
                }
              ],
              "fee": 8,
              "max_limit": 10000,
              "min_limit": 0,
              "source_amount": 104.3,
              "number_of_locations": 13007,
              "estimated_availability": "2020-07-21T17:32:28Z",
              "additional_description": "Requires drivers license to pickup funds"
            }
          ]
        }
      ],
      "rating": 4.5,
      "description": "Pontual is a top leading provider with over 10 years of industry experience",
      "company_name": "Pontual"
    }
  ]
}

👍

200-OK Response?

As a response, you will get all information about companies that matched your search. Make sure that you pay attention to the destination_token. You will need it in the next step.

Step four: Get and store user attributes for Destination token

When you sending payments using MassPay, it is important to have accurate and up-to-date information about the recipients. To help you manage this information, MassPay provides APIs for retrieving and storing user attributes for destination tokens. In this step we will get and also store user attributes in a simple process.

1. Open your Postman and import OpenApi specification with GET /attribute/{user_token}/{destination_token}/{currency}.

📘

You can find out OpenApi specification here.

2. Fill environment, version , user_token, destination_token and currency to the Header and Bearer access-token as Authorization method.
3. Call the REST API. Your response should look like this:

[
  {
    "token": "attr_e2ca24e9-c546-4c64-90d2-cb8e70e7c9ba",
    "attr_set_token": "attr_set_e2ca24e9-c546-4c64-90d2-cb8e70e7c9ba",
    "label": "Checking Account Number",
    "validation": "[0-9]{50}",
    "is_optional": true,
    "value": "432532532",
    "expected_value": "Date format MM/DD/YYYY",
    "type": "BankAccountNumber",
    "input_type": "text"
  }
]

👍

200-OK Response?

As a response, you will get all required attributes for the provider user for a particular destination token. As a next step, you will store your user attributes.

4. Open your Postman and import OpenApi specification with POST /attribute/{user_token}/{destination_token}/{currency}.

📘

You can find out OpenApi specification here.

5. Fill environment, version , user_token, destination_token and currency to the Header and Bearer access-token as Authorization method.
6. Fill the Body parameters.
7. Call the REST API.

👍

200-OK Response?

Your successfully store your user attributes.

Step five: Initiate a payout transaction

To initiate a payout transaction, you'll need to send a POST request to the MassPay API with the required parameters, including the amount to be paid, the recipient's information, and any additional information required by your payout method. The API will respond with a payout token, which you can use to retrieve the status and confirmation details of the transaction later.

1. Open your Postman and import OpenApi specification with POST /payout/{user_token}.

📘

You can find our OpenApi specification here.

2. Fill environment, version and user_token to the Header and Bearer access-token as Authorization method.

Header

3. Fill the Body parameters with details about your payout:

👍

Make sure to check our API specification for all the details about each parameter.

Your Body should look like this:

{
  "source_currency_code": "USD",
  "metadata": {
    "newKey": "\"group_id\":541"
  },
  "notify_user": true,
  "client_transfer_id": "aEjn345",
  "destination_currency_code": "MXN",
  "source_token": "123e4567-e89b-12d3-a456-426614174000",
  "destination_token": "123e4567-e89b-12d3-a456-426614174000",
  "destination_amount": 100.5,
  "source_amount": 100.5,
  "attr_set_token": "123e4567-e89b-12d3-a456-426614174000"
}

4. Call the REST API. Your response should look like this:

{
  "payout_token": "ba4275f2-bae1-488d-9d6f-20af1cd83574",
  "client_transfer_id": "aEjn345",
  "source_currency_code": "USD",
  "destination_currency_code": "MXN",
  "source_token": "ba4275f2-bae1-488d-9d6f-20af1cd83574",
  "destination_token": "d2138fd0-00be-45a8-985f-4f5bde500962",
  "destination_amount": 100.5,
  "source_amount": 100.5,
  "attr_set_token": "b1a867c1-6e36-4525-b6d5-a20bac80e3b0",
  "exchange_rate": 18.55,
  "fee": 2.99,
  "expiration": "2019-06-26T22:32:05",
  "pickup_code": "54238173",
  "status": "PENDING",
  "payer_logo": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAMgAAADICAIAAAAiOjnJAAAABGdBTUEAALGP...",
  "payer_name": "Elektra",
  "delivery_type": "CASH_PICKUP",
  "country_code": "MEX",
  "metadata": {
    "group_id": 541
  },
  "estimated_availability": "2020-07-21T17:32:28Z"
}

👍

200-OK Response?

As a response, you will get all information about your transaction. Make sure that you pay attention to the status of your transaction and estimated_availability.

Step six: Commit your payout

Once you have created your payout transaction using the MassPay API, the final step is to commit the payment. Committing a payout transaction will initiate the transfer of funds from your MassPay account to the recipients you specified in the transaction.

❗️

It is important to note that once a payout transaction has been committed, it cannot be cancelled or reversed.

Therefore, it is important to ensure that all transaction details are accurate before committing the payment.

1. Open your Postman and import OpenApi specification with PUT/ payout/{user_token}/{payout_token}.

📘

You can find our OpenApi specification here.

2. Fill environment, version ,user_token and payout_token to the Header and Bearer access-token as Authorization method.
3. Call the REST API. Your response should look like this:

{
  "payout_token": "payout_ba4275f2-bae1-488d-9d6f-20af1cd83574",
  "status": "success",
  "pickup_code": "54238173",
  "errors": "Duplicate transfer"
}

👍

200-OK Response?

If you get 200 OK Response, make sure, that you check status of your payout.

If success, everything was processed correctly. failure indicates a generic error. addtl_attr_req indicates that in order to process this transaction, additional attributes are required to be updated for this customer. ex_rate_expired indicates that the transaction exchange rate has expired and a new transaction has to be created.

And that's it. You just went through the whole process of creating a new transaction and submitting it. Congratulations!

More?

In addition to the whole process for creating a payout transaction, MassPay API provides additional APIs that you can use to retrieve and export information about your payouts.

1. Check status: This API allows the user to retrieve the status of a previously initiated payout transaction. The user must provide the payout token for the transaction in order to retrieve the status information.

📘

You can find the “Check status” API here.

2. Check status and export PDF: This API not only retrieves the status of a previously initiated payout transaction but also generates a PDF file with detailed information about the transaction. The user must provide the payout token for the transaction in order to retrieve the status information and generate the PDF file.

📘

You can find “Check status and export PDF” here.