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.
- Open your Postman and import OpenApi specification with
GET /account/balance
.
You can find our OpenApi specification here.
- Fill the
environment
andversion
to the Header andBearer access-token
as Authorization method.
Header
Parameter | Description | Possible values |
---|---|---|
environment | Select the version of the API environment you want to use. | - api - staging-api |
version | Select the version of API you want to use. | - v0.1.4 - v1.0.0 |
curl -X GET https://{environment}.masspay.io/{VERSION}/account/balance \
-H 'Accept: application/json' \
-H 'Authorization: Bearer {access-token}'
- 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.
- Open your Postman and import OpenApi specification with
POST /user
.
You can find our OpenApi specification here.
- Fill the
environment
andversion
to the Header andBearer access-token
as Authorization method.
Header
Parameter | Description | Possible values |
---|---|---|
environment | Select the version of the API environment you want to use. | - api - staging-api |
version | Select the version of API you want to use. | - v0.1.4 - v1.0.0 |
- Fill the Body parameters according to your customers provided information.
- 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.
- Open your Postman and import OpenApi specification with
GET /country/{country_code}/cheapest
.
You can find our OpenApi specification here.
- Fill
environment
,version
andcountry_code
to the Header andBearer access-token
as Authorization method.
Header
Parameter | Description | Possible values |
---|---|---|
environment | Select the version of the API environment you want to use. | - api - staging-api |
version | Select the version of API you want to use. | - v0.1.4 - v1.0.0 |
country_code | Country code searching services for. 3 letters ISO_3166 code" | - |
Good to know...
You can narrow your search using our optional parameters such as e.g.:
source_currency
,wallet_token
,limit
, ...
- Call the REST API. Your response should look like this:
{
"companies": [
{
"company_logo": "U3dhZ2dlciByb2Nrcw==",
"services": [
{
"country_code": "MEX",
"delivery_type": "CASH_PICKUP",
"payers": [
{
"destination_token": "123e4567-e89b-12d3-a456-426614174000",
"payer_logo": "U3dhZ2dlciByb2Nrcw==",
"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",
"is_dynamic_token": true
}
]
}
],
"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.
- Open your Postman and import OpenApi specification with
GET /attribute/{user_token}/{destination_token}/{currency}
.
You can find out OpenApi specification here.
- Fill
environment
,version
,user_token
,destination_token
andcurrency
to the Header andBearer access-token
as Authorization method. - 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",
"last_attr_value_used": true
}
]
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.
- Open your Postman and import OpenApi specification with
POST /attribute/{user_token}/{destination_token}/{currency}
.
You can find out OpenApi specification here.
- Fill
environment
,version
,user_token
,destination_token
andcurrency
to the Header andBearer access-token
as Authorization method. - Fill the Body parameters.
- 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.
- Open your Postman and import OpenApi specification with
POST /payout/{user_token}
.
You can find our OpenApi specification here.
- Fill
environment
,version
anduser_token
to the Header andBearer access-token
as Authorization method.
Header
Parameter | Description | Possible values |
---|---|---|
environment | Select the version of the API environment you want to use. | - api - staging-api |
version | Select the version of API you want to use. | - v0.1.4 - v1.0.0 |
user_token | Token representing the user to load. |
- Fill the Body parameters with details about your payout:
Parameter | Description | Example values | Required? |
---|---|---|---|
client_transfer_id | A client defined transfer identifier. This is the unique ID assigned to the transfer on your system. | aEjn345 | NO |
source_currency_code | The currency originating balance is stored in. Using ISO 4217 format. | USD | NO |
destination_currency_code | The currency the funds will be deposited into. Using ISO 4217 format. | MXN | YES |
source_token | Token represents the funding source, such as bank account or wallet. | usr_ba4275f2-bae1-488d-9d6f-20af1cd83574 | YES |
destination_token | Token that represents the payout destination. | dest_ba4275f2-bae1-488d-9d6f-20af1cd83574 | YES |
destination_amount | The amount to be sent for payout in source currency. | 100.5 | YES, if source_amount is not provided |
source_amount | The amount to be received by the payout in source currency. | 100.5 | YES, if destination_amount is not provided |
attr_set_token | Token that represents set of attributes that associated with destination_token . | attr_set_123e4567-e89b-12d3-a456-426614174000 | NO |
metadata | Optional JSON object with attributes that can later be searched to locate this payout. | {"field":"value"} | NO |
notify_user | Possibility to notify users via email/SMS. | true | NO |
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"
}
- 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": "U3dhZ2dlciByb2Nrcw==",
"payer_name": "Elektra",
"delivery_type": "CASH_PICKUP",
"country_code": "MEX",
"metadata": {
"group_id": 541
},
"estimated_availability": "2020-07-21T17:32:28Z",
"status_reason": "string",
"attrs": {}
}
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.
- Open your Postman and import OpenApi specification with
PUT/ payout/{user_token}/{payout_token}
.
You can find our OpenApi specification here.
- Fill
environment
,version
,user_token
andpayout_token
to the Header andBearer access-token
as Authorization method. - 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.
- 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.
- 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.
Updated about 11 hours ago