Introduction

Welcome to the MassPay API documentation! Our API will give you the functionality to add beneficiaries, fund wallets, initiate transfers.

We have language bindings in Shell, Ruby, Python, Java and JavaScript! You can view code examples in the dark area to the right, and you can switch the programming language of the examples with the tabs in the top right.

Our API utilizes versioning and will therefore have different functionality based on the version set up in your account.

Making Requests

All requests and responses are JSON encoded. Requests must be made over SSL connections using HTTPS. Requests made over HTTP will be redirected to HTTPS.

Authentication

HTTP Authentication, scheme: bearer

The MassPay API uses API keys to allow access to the API. You can register a new MassPay API key at our developer portal.

Do not share your secret API keys in publicly accessible areas such as GitHub, BitBucket, Open Source projects or client scripts.

MassPay API expects for the API key to be included in all API requests to the server in a header that looks like the following:

Authorization: bearer API_KEY

You must replace API_KEY with your personal API key.

Idempotent Requests

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 charge is created.

To perform an idempotent request, provide an additional Idempotency-Key: <key> header to the request.

MassPay's idempotency works by saving the resulting status code and body of the first request made for any given idempotency key, regardless of whether it succeeded or failed. Subsequent requests with the same key return the same result, including 500 errors.

An idempotency key is a unique value generated by the client which the server uses to recognize subsequent retries of the same request. How you create unique keys is up to you, but we suggest using V4 UUIDs, or another random string with enough entropy to avoid collisions.

Keys expire after 24 hours, so a new request is generated if a key is reused outside of that time frame. The idempotency layer compares incoming parameters to those of the original request and errors unless they're the same to prevent accidental misuse.

Results are only saved if an API endpoint started executing. If incoming parameters failed validation, or the request conflicted with another that was executing concurrently, no idempotent result is saved because no API endpoint began execution. It is safe to retry these requests.

Versioning

When we make backwards-incompatible changes to the API, we release new, dated versions. The current version is 0.0.3. Read our API upgrades guide to see our API changelog and to learn more about backwards compatibility.

To set the API version on a specific request, pass the version in the url. i.e. https://api.masspay.io/VERSION

Status Callbacks

There is support for initiating a callback to an https URL every time there is a status update to one of the payout transactions.
In order to enable this feature, please provide a callback URL to your account representative. The URL will receive a POST request with the following payload format for every status change for a transaction.

Enumerated Values

Property

Value

status

PENDING

status

COMPLETED

status

CANCELLED

status

READY_FOR_PICKUP

status

HOLD

User

A user represents an individual or a business that can receive payments, such as employees, survey participants, contractors, or distributors. Users can withdraw funds using any of MassPay's supported payout options, including but not limited to bank accounts, debit card, PayPal account, prepaid cards, cash pickup locations, mobile wallets, etc. All payout options for a user are attached to their user resource, so you will always need to create users.

To create a user, send a POST request to the /user endpoint and include the user details in JSON format in the request body. Upon creation of a user, you'll receive a user_token which would be used to interact with that user.

Retrieve list of all tranasctions (payouts/loads/spendbacks) for a provider user

Parameters

Name

In

Type

Required

Description

Idempotency-Key

header

string

false

Unique key to prevent duplicate processing

number_of_records

query

number

false

Number of records to return

start_date

query

string

false

Starting date

end_date

query

string

false

Ending date

page

query

integer

false

Page number

user_token

path

string

true

Token representing the user to get transactions history for

Example responses

200 Response

[{"token":"d2138fd0-00be-45a8-985f-4f5b87500962","type":"payout","time_of_txn":"2020-05-28T00:27:32Z","source_amount":50.1,"source_currency_code":"USD","destination_amount":44.99,"destination_currency_code":"str","fee":2.98,"status":"READY_FOR_PICKUP","notes":"Purchase of Candles. Order #14930","payer_name":"Elektra","pickup_code":"343432"}]

Token that represents the payout destination i.e. Omnex->Brazil->Bank Deposit->Itau. To be retrieved from the #pricing callback. If not provided, the last destination that was used for this user will be used. 36 characters long

» destination_amount

number(float)

true

none

The amount to be sent for payout in source currency. i.e USD. Must be provided if source_amount is empty

» source_amount

number(float)

true

none

The amount to be received by the payout in destination currency. i.e MXN. Must be provided if destination_amount is empty

» attr_set_token

string(uuid)

true

none

Token that represents set of attributes that associated with destination_token. For example, bank account, mobile account, wallet id, etc. If not provided, uses the last one used. 36 characters long

» exchange_rate

number(float)

true

none

The exchange rate to convert source_amount to destination_amount

» fee

number(float)

true

none

Fee to be charged for the transaction

» expiration

string(YYYY-MMDDThh:mm:ss)

true

none

The time and date at which the transaction will expire. The transaction has to be finalized before this time. Transactions are valid for 2 minutes from creation time. If expired, a new transaction has to be created.

» pickup_code

string

true

none

Code/pin that is required when collecting the money. Should be provided to the recipient to present to payout location.

Gets a list of Companies and their service offerings for the given country code.

Gets a list of all the available services and pricing for each respected company for a provided country code.

Parameters

Name

In

Type

Required

Description

country_code

path

string

true

Country code searching services for

amount

query

string

false

Returns the results fee based on the given amount, defaults to $200

limit

query

number

false

Limit amount for transaction amount + fee. If fee + amount are higher than the limit, the output will automatically adjust to maximize the possible amount sent

Idempotency-Key

header

string

false

Unique key to prevent duplicate processing

Example responses

200 Response

{"companies":[{"company_logo":"data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAMgAAADICAIAAAAiOjnJAAAABGdBTUEAALGP...","services":[{"country_code":"MX","delivery_type":"CASH_PICKUP","payers":[{"destination_token":"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}]}],"rating":4.5,"description":"Pontual is a top leading provider with over 10 years of industry experience","company_name":"Pontual"}]}

Token that represents the payout destination i.e. Omnex->Brazil->Bank Deposit->Itau. To be retrieved from the #pricing callback. If not provided, the last destination that was used for this user will be used. 36 characters long

destination_amount

number(float)

false

none

The amount to be sent for payout in source currency. i.e USD. Must be provided if source_amount is empty

source_amount

number(float)

false

none

The amount to be received by the payout in destination currency. i.e MXN. Must be provided if destination_amount is empty

attr_set_token

string(uuid)

false

none

Token that represents set of attributes that associated with destination_token. For example, bank account, mobile account, wallet id, etc. If not provided, uses the last one used. 36 characters long

Token that represents the payout destination i.e. Omnex->Brazil->Bank Deposit->Itau. To be retrieved from the #pricing callback. If not provided, the last destination that was used for this user will be used. 36 characters long

destination_amount

number(float)

true

none

The amount to be sent for payout in source currency. i.e USD. Must be provided if source_amount is empty

source_amount

number(float)

true

none

The amount to be received by the payout in destination currency. i.e MXN. Must be provided if destination_amount is empty

attr_set_token

string(uuid)

true

none

Token that represents set of attributes that associated with destination_token. For example, bank account, mobile account, wallet id, etc. If not provided, uses the last one used. 36 characters long

exchange_rate

number(float)

true

none

The exchange rate to convert source_amount to destination_amount

fee

number(float)

true

none

Fee to be charged for the transaction

expiration

string(YYYY-MMDDThh:mm:ss)

true

none

The time and date at which the transaction will expire. The transaction has to be finalized before this time. Transactions are valid for 2 minutes from creation time. If expired, a new transaction has to be created.

pickup_code

string

true

none

Code/pin that is required when collecting the money. Should be provided to the recipient to present to payout location.

PayoutTxnCommitResp

Properties

Name

Type

Required

Restrictions

Description

payout_token

string(uuid)

true

none

Token that represents the transaction that was just created.

status

string

true

none

Status that indicates whether the transaction was successfully processed. 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.

pickup_code

string

false

none

Code/pin that is required when collecting the money. Should be provided to the recipient to present to payout location.

errors

string

false

none

Description of errors preventing transfer from being injected.

Enumerated Values

Property

Value

status

success

status

failure

status

addtl_attr_req

status

ex_rate_expired

status

nsf

Country

{"code":"MX","name":"Mexico"}

Properties

CompaniesResp

{"companies":[{"company_logo":"data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAMgAAADICAIAAAAiOjnJAAAABGdBTUEAALGP...","services":[{"country_code":"MX","delivery_type":"CASH_PICKUP","payers":[{"destination_token":"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}]}],"rating":4.5,"description":"Pontual is a top leading provider with over 10 years of industry experience","company_name":"Pontual"}]}

Properties

Company

{"company_logo":"data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAMgAAADICAIAAAAiOjnJAAAABGdBTUEAALGP...","services":[{"country_code":"MX","delivery_type":"CASH_PICKUP","payers":[{"destination_token":"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}]}],"rating":4.5,"description":"Pontual is a top leading provider with over 10 years of industry experience","company_name":"Pontual"}

The currency originating balance is stored in. Using ISO 4217 format. In most cases this value will be USD, and therefore the defaut value if none is provided

amount

number

true

none

The amount to debit the user's wallet in source currency

notes

string

false

none

A description for the spend back

TxnHistoryResp

{"token":"d2138fd0-00be-45a8-985f-4f5b87500962","type":"payout","time_of_txn":"2020-05-28T00:27:32Z","source_amount":50.1,"source_currency_code":"USD","destination_amount":44.99,"destination_currency_code":"str","fee":2.98,"status":"READY_FOR_PICKUP","notes":"Purchase of Candles. Order #14930","payer_name":"Elektra","pickup_code":"343432"}

TxnHistoryResp

Properties

Name

Type

Required

Restrictions

Description

token

string(uuid)

true

none

Token represnting the transaction

type

string

true

none

Type of transaction

time_of_txn

string(date-time)

true

none

Time the transaction was created

source_amount

number(float)

true

none

Source amount

source_currency_code

string

true

none

The currency originating balance is stored in. Using ISO 4217 format. In most cases this value will be USD, and therefore the defaut value if none is provided