NAV
curl Python Ruby java csharp

MassPay API v0.1.1

Scroll down for code samples, example requests and responses. Select a language for code samples from the tabs above or the mobile navigation menu.

MassPay API

Base URLs:

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

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

{
  "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-10-30T05:40:58.475Z",
  "status": "PENDING"
}

Changelog

0.1.0 to 0.1.1:

0.0.3 to 0.1.0:

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.

createUser

Code samples

# You can also use wget
curl -X POST https://{environment}.masspay.io/{VERSION}/user \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer {access-token}'

import requests
headers = {
  'Content-Type': 'application/json',
  'Accept': 'application/json',
  'Authorization': 'Bearer {access-token}'
}

r = requests.post('https://{environment}.masspay.io/{VERSION}/user', params={

}, headers = headers)

print r.json()

require 'rest-client'
require 'json'

headers = {
  'Content-Type' => 'application/json',
  'Accept' => 'application/json',
  'Authorization' => 'Bearer {access-token}'
}

result = RestClient.post 'https://{environment}.masspay.io/{VERSION}/user',
  params: {
  }, headers: headers

p JSON.parse(result)

URL obj = new URL("https://{environment}.masspay.io/{VERSION}/user");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("POST");
int responseCode = con.getResponseCode();
BufferedReader in = new BufferedReader(
    new InputStreamReader(con.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
    response.append(inputLine);
}
in.close();
System.out.println(response.toString());

POST /user

Create a user

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.

Body parameter

{
  "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": "jdoe@gmail.com",
  "language": "en",
  "mobile_number": "16502000226",
  "business_name": "ABC Company"
}

Parameters

Name In Type Required Description
body body User true Created user object

Example responses

200 Response

{
  "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": "jdoe@gmail.com",
  "language": "en",
  "mobile_number": "16502000226",
  "business_name": "ABC Company"
}

Responses

Status Meaning Description Schema
200 OK successful operation StoredUser
403 Forbidden You do not have necessary permissions for the resource None
405 Method Not Allowed Invalid input Exception

getUserByToken

Code samples

# You can also use wget
curl -X GET https://{environment}.masspay.io/{VERSION}/user/{user_token} \
  -H 'Accept: application/json' \
  -H 'Idempotency-Key: string' \
  -H 'Authorization: Bearer {access-token}'

import requests
headers = {
  'Accept': 'application/json',
  'Idempotency-Key': 'string',
  'Authorization': 'Bearer {access-token}'
}

r = requests.get('https://{environment}.masspay.io/{VERSION}/user/{user_token}', params={

}, headers = headers)

print r.json()

require 'rest-client'
require 'json'

headers = {
  'Accept' => 'application/json',
  'Idempotency-Key' => 'string',
  'Authorization' => 'Bearer {access-token}'
}

result = RestClient.get 'https://{environment}.masspay.io/{VERSION}/user/{user_token}',
  params: {
  }, headers: headers

p JSON.parse(result)

URL obj = new URL("https://{environment}.masspay.io/{VERSION}/user/{user_token}");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("GET");
int responseCode = con.getResponseCode();
BufferedReader in = new BufferedReader(
    new InputStreamReader(con.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
    response.append(inputLine);
}
in.close();
System.out.println(response.toString());

GET /user/{user_token}

Get user by user token

Gets a user profile for a provided user token.

Parameters

Name In Type Required Description
user_token path string true The user token that needs to be fetched.
Idempotency-Key header string false Unique key to prevent duplicate processing

Example responses

200 Response

{
  "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": "jdoe@gmail.com",
  "language": "en",
  "mobile_number": "16502000226",
  "business_name": "ABC Company"
}

Responses

Status Meaning Description Schema
200 OK successful operation StoredUser
400 Bad Request Invalid user token supplied None
404 Not Found User not found None

updateUser

Code samples

# You can also use wget
curl -X PUT https://{environment}.masspay.io/{VERSION}/user/{user_token} \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'Idempotency-Key: string' \
  -H 'Authorization: Bearer {access-token}'

import requests
headers = {
  'Content-Type': 'application/json',
  'Accept': 'application/json',
  'Idempotency-Key': 'string',
  'Authorization': 'Bearer {access-token}'
}

r = requests.put('https://{environment}.masspay.io/{VERSION}/user/{user_token}', params={

}, headers = headers)

print r.json()

require 'rest-client'
require 'json'

headers = {
  'Content-Type' => 'application/json',
  'Accept' => 'application/json',
  'Idempotency-Key' => 'string',
  'Authorization' => 'Bearer {access-token}'
}

result = RestClient.put 'https://{environment}.masspay.io/{VERSION}/user/{user_token}',
  params: {
  }, headers: headers

p JSON.parse(result)

URL obj = new URL("https://{environment}.masspay.io/{VERSION}/user/{user_token}");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("PUT");
int responseCode = con.getResponseCode();
BufferedReader in = new BufferedReader(
    new InputStreamReader(con.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
    response.append(inputLine);
}
in.close();
System.out.println(response.toString());

PUT /user/{user_token}

Updated user

Updates profile information for a provided user token. This can only be done by the logged in user.

Body parameter

{
  "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": "jdoe@gmail.com",
  "language": "en",
  "mobile_number": "16502000226"
}

Parameters

Name In Type Required Description
user_token path string true user token that need to be updated
Idempotency-Key header string false Unique key to prevent duplicate processing
body body UpdateUser true Updated user object

Example responses

200 Response

{
  "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": "jdoe@gmail.com",
  "language": "en",
  "mobile_number": "16502000226",
  "business_name": "ABC Company"
}

Responses

Status Meaning Description Schema
200 OK successful operation StoredUser
400 Bad Request Invalid user supplied None
404 Not Found User not found None

userLookup

Code samples

# You can also use wget
curl -X GET https://{environment}.masspay.io/{VERSION}/user/lookup?email=string&first_name=string \
  -H 'Accept: application/json' \
  -H 'Idempotency-Key: string' \
  -H 'Authorization: Bearer {access-token}'

import requests
headers = {
  'Accept': 'application/json',
  'Idempotency-Key': 'string',
  'Authorization': 'Bearer {access-token}'
}

r = requests.get('https://{environment}.masspay.io/{VERSION}/user/lookup', params={
  'email': 'string',  'first_name': 'string'
}, headers = headers)

print r.json()

require 'rest-client'
require 'json'

headers = {
  'Accept' => 'application/json',
  'Idempotency-Key' => 'string',
  'Authorization' => 'Bearer {access-token}'
}

result = RestClient.get 'https://{environment}.masspay.io/{VERSION}/user/lookup',
  params: {
  'email' => 'string',
'first_name' => 'string'
}, headers: headers

p JSON.parse(result)

URL obj = new URL("https://{environment}.masspay.io/{VERSION}/user/lookup?email=string&first_name=string");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("GET");
int responseCode = con.getResponseCode();
BufferedReader in = new BufferedReader(
    new InputStreamReader(con.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
    response.append(inputLine);
}
in.close();
System.out.println(response.toString());

GET /user/lookup

Lookup an existing user

Looksup whether a user with the provided email and first name exist

Parameters

Name In Type Required Description
Idempotency-Key header string false Unique key to prevent duplicate processing
email query string true User's email address
first_name query string true User's first name

Example responses

405 Response

{
  "Exception": "string",
  "Errors": [
    "string"
  ]
}

Responses

Status Meaning Description Schema
200 OK Found a matching user FoundUser
403 Forbidden You do not have necessary permissions for the resource None
404 Not Found A user matching this email and first name could not be found None
405 Method Not Allowed Invalid input Exception

getUserHistory

Code samples

# You can also use wget
curl -X GET https://{environment}.masspay.io/{VERSION}/user/{user_token}/history \
  -H 'Accept: application/json' \
  -H 'Idempotency-Key: string' \
  -H 'Authorization: Bearer {access-token}'

import requests
headers = {
  'Accept': 'application/json',
  'Idempotency-Key': 'string',
  'Authorization': 'Bearer {access-token}'
}

r = requests.get('https://{environment}.masspay.io/{VERSION}/user/{user_token}/history', params={

}, headers = headers)

print r.json()

require 'rest-client'
require 'json'

headers = {
  'Accept' => 'application/json',
  'Idempotency-Key' => 'string',
  'Authorization' => 'Bearer {access-token}'
}

result = RestClient.get 'https://{environment}.masspay.io/{VERSION}/user/{user_token}/history',
  params: {
  }, headers: headers

p JSON.parse(result)

URL obj = new URL("https://{environment}.masspay.io/{VERSION}/user/{user_token}/history");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("GET");
int responseCode = con.getResponseCode();
BufferedReader in = new BufferedReader(
    new InputStreamReader(con.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
    response.append(inputLine);
}
in.close();
System.out.println(response.toString());

GET /user/{user_token}/history

Transactions history

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(date) false Starting date
end_date query string(date) false Ending date
page query integer false Page number
type query string false Filter particular types of transactions. Comma separated to include multiple types
wallet_token query string(uuid) false Filter transactions to include only provided wallet token.
user_token path string true Token representing the user to get transactions history for

Enumerated Values

Parameter Value
type payout
type load
type spendback

Example responses

200 Response

[
  {
    "token": "payout_d2138fd0-00be-45a8-985f-4f5b87500962",
    "type": "payout",
    "time_of_txn": "2020-09-11T04:07:10Z",
    "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",
    "source_token": "usr_wlt_ba4275f2-bae1-488d-9d6f-20af1cd83574",
    "destination_token": "dest_d2138fd0-00be-45a8-985f-4f5bde500962",
    "delivery_type": "CASH_PICKUP"
  }
]

Responses

Status Meaning Description Schema
200 OK OK Inline

Response Schema

Status Code 200

Name Type Required Restrictions Description
anonymous [TxnHistoryResp] false none [Record that represents a transaction]
» TxnHistoryResp TxnHistoryResp false none Record that represents a transaction
»» 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
»» destination_amount number(float) true none The amount that was received in destination_currency_code
»» destination_currency_code string true none The currency of the funds received. Using ISO 4217 format
»» fee number(float) true none Fee of the transaction
»» status string true none Status of the transaction
»» notes string false none Notes of the transaction when load or spend back
»» payer_name string false none Name of the payer when payout transaction
»» pickup_code string false none Code/pin that is required when collecting the money when payout transaction
»» source_token string(uuid) false none Token that represents the funding source i.e. bank account, wallet. 36 characters long
»» destination_token string(uuid) true none 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
»» delivery_type string false none The type of service. I.e. cash pickup, home delivery, etc. Only provided for payouts

Enumerated Values

Property Value
type load
type payout
type spend back
type info
status PENDING
status PROCESSING
status COMPLETED
status CANCELLED
status READY_FOR_PICKUP
status HOLD
status ERROR
delivery_type CASH_PICKUP
delivery_type BANK_DEPOSIT
delivery_type HOME_DELIVERY
delivery_type MOBILE_WALLET
delivery_type MASSPAY_CARD

Payout

The payout resource describes a transfer from user’s account to a payout method.

initiatePayout

Code samples

# You can also use wget
curl -X POST https://{environment}.masspay.io/{VERSION}/payout/{user_token} \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'Idempotency-Key: string' \
  -H 'Authorization: Bearer {access-token}'

import requests
headers = {
  'Content-Type': 'application/json',
  'Accept': 'application/json',
  'Idempotency-Key': 'string',
  'Authorization': 'Bearer {access-token}'
}

r = requests.post('https://{environment}.masspay.io/{VERSION}/payout/{user_token}', params={

}, headers = headers)

print r.json()

require 'rest-client'
require 'json'

headers = {
  'Content-Type' => 'application/json',
  'Accept' => 'application/json',
  'Idempotency-Key' => 'string',
  'Authorization' => 'Bearer {access-token}'
}

result = RestClient.post 'https://{environment}.masspay.io/{VERSION}/payout/{user_token}',
  params: {
  }, headers: headers

p JSON.parse(result)

URL obj = new URL("https://{environment}.masspay.io/{VERSION}/payout/{user_token}");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("POST");
int responseCode = con.getResponseCode();
BufferedReader in = new BufferedReader(
    new InputStreamReader(con.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
    response.append(inputLine);
}
in.close();
System.out.println(response.toString());

POST /payout/{user_token}

Initiate a payout transaction

Initiates a payout transaction to a provided user token.

Body parameter

{
  "client_transfer_id": "aEjn345",
  "source_currency_code": "USD",
  "destination_currency_code": "MXN",
  "source_token": "usr_wlt_ba4275f2-bae1-488d-9d6f-20af1cd83574",
  "destination_token": "dest_d2138fd0-00be-45a8-985f-4f5bde500962",
  "destination_amount": 100.5,
  "source_amount": 100.5,
  "attr_set_token": "attr_set_b1a867c1-6e36-4525-b6d5-a20bac80e3b0"
}

Parameters

Name In Type Required Description
user_token path string true Token representing the user to pay out
Idempotency-Key header string false Unique key to prevent duplicate processing
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
body body PayoutTxn true Payout parameters for a quote

Example responses

200 Response

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

Responses

Status Meaning Description Schema
200 OK successful operation PayoutTxnResp
403 Forbidden You do not have necessary permissions for the resource None
405 Method Not Allowed Invalid input Exception

getUserPayoutsByToken

Code samples

# You can also use wget
curl -X GET https://{environment}.masspay.io/{VERSION}/payout/{user_token} \
  -H 'Accept: application/json' \
  -H 'Idempotency-Key: string' \
  -H 'Authorization: Bearer {access-token}'

import requests
headers = {
  'Accept': 'application/json',
  'Idempotency-Key': 'string',
  'Authorization': 'Bearer {access-token}'
}

r = requests.get('https://{environment}.masspay.io/{VERSION}/payout/{user_token}', params={

}, headers = headers)

print r.json()

require 'rest-client'
require 'json'

headers = {
  'Accept' => 'application/json',
  'Idempotency-Key' => 'string',
  'Authorization' => 'Bearer {access-token}'
}

result = RestClient.get 'https://{environment}.masspay.io/{VERSION}/payout/{user_token}',
  params: {
  }, headers: headers

p JSON.parse(result)

URL obj = new URL("https://{environment}.masspay.io/{VERSION}/payout/{user_token}");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("GET");
int responseCode = con.getResponseCode();
BufferedReader in = new BufferedReader(
    new InputStreamReader(con.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
    response.append(inputLine);
}
in.close();
System.out.println(response.toString());

GET /payout/{user_token}

Get history of payouts by user token

Gets a list of all historical payouts for a provided user token.

Parameters

Name In Type Required Description
user_token path string true The user token that needs to be fetched.
Idempotency-Key header string false Unique key to prevent duplicate processing
include_payer_logos query boolean false Whether to include the payers logo in base64 format.

Example responses

200 Response

[
  {
    "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": "MX"
  }
]

Responses

Status Meaning Description Schema
200 OK successful operation Inline
400 Bad Request Invalid user token supplied None
404 Not Found User not found None

Response Schema

Status Code 200

Name Type Required Restrictions Description
anonymous [PayoutTxnResp] false none none
» payout_token string(uuid) true none Token that represents the transaction that was just created. Need to be used to commit the transaction in /payout/{user_token}/{payout_token}. Value would be NSF if there are not enough funds in the source_token. Value would be DUPLICATE if there is a duplicate client_transfer_id.
» client_transfer_id string true none A client defined transfer identifier. This is the unique ID assigned to the transfer on your system. Max 50 characters.
» 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
» destination_currency_code string true none The currency the funds will be deposited into. Using ISO 4217 format
» source_token string(uuid) true none Token that represents the funding source i.e. your bank account, user's wallet. 36 characters long
» destination_token string(uuid) true none 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.
» status string true none The status of the transaction
» payer_logo string(byte) false none base64 representation of the payer logo
» payer_name string false none Name of payer
» delivery_type string false none none
» country_code string false none Country code ISO_3166

Enumerated Values

Property Value
status PENDING
status PROCESSING
status COMPLETED
status CANCELLED
status READY_FOR_PICKUP
status HOLD
status ERROR
delivery_type CASH_PICKUP
delivery_type BANK_DEPOSIT
delivery_type HOME_DELIVERY
delivery_type MOBILE_WALLET
delivery_type MASSPAY_CARD

commitPayoutTxn

Code samples

# You can also use wget
curl -X PUT https://{environment}.masspay.io/{VERSION}/payout/{user_token}/{payout_token} \
  -H 'Accept: application/json' \
  -H 'Idempotency-Key: string' \
  -H 'Authorization: Bearer {access-token}'

import requests
headers = {
  'Accept': 'application/json',
  'Idempotency-Key': 'string',
  'Authorization': 'Bearer {access-token}'
}

r = requests.put('https://{environment}.masspay.io/{VERSION}/payout/{user_token}/{payout_token}', params={

}, headers = headers)

print r.json()

require 'rest-client'
require 'json'

headers = {
  'Accept' => 'application/json',
  'Idempotency-Key' => 'string',
  'Authorization' => 'Bearer {access-token}'
}

result = RestClient.put 'https://{environment}.masspay.io/{VERSION}/payout/{user_token}/{payout_token}',
  params: {
  }, headers: headers

p JSON.parse(result)

URL obj = new URL("https://{environment}.masspay.io/{VERSION}/payout/{user_token}/{payout_token}");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("PUT");
int responseCode = con.getResponseCode();
BufferedReader in = new BufferedReader(
    new InputStreamReader(con.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
    response.append(inputLine);
}
in.close();
System.out.println(response.toString());

PUT /payout/{user_token}/{payout_token}

Commit payout transaction

Commits a previously initiated transaction.

Parameters

Name In Type Required Description
user_token path string true Token representing the user to pay out
payout_token path string true Token representing the trsanaction. Retrieved from /payout/{user_token}
Idempotency-Key header string false Unique key to prevent duplicate processing

Example responses

200 Response

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

Responses

Status Meaning Description Schema
200 OK successful operation PayoutTxnCommitResp
403 Forbidden You do not have necessary permissions for the resource None
405 Method Not Allowed Invalid input Exception

Load

The load resource describes a load of balance into a user's wallet.

loadUser

Code samples

# You can also use wget
curl -X POST https://{environment}.masspay.io/{VERSION}/load/{user_token} \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'Idempotency-Key: string' \
  -H 'Authorization: Bearer {access-token}'

import requests
headers = {
  'Content-Type': 'application/json',
  'Accept': 'application/json',
  'Idempotency-Key': 'string',
  'Authorization': 'Bearer {access-token}'
}

r = requests.post('https://{environment}.masspay.io/{VERSION}/load/{user_token}', params={

}, headers = headers)

print r.json()

require 'rest-client'
require 'json'

headers = {
  'Content-Type' => 'application/json',
  'Accept' => 'application/json',
  'Idempotency-Key' => 'string',
  'Authorization' => 'Bearer {access-token}'
}

result = RestClient.post 'https://{environment}.masspay.io/{VERSION}/load/{user_token}',
  params: {
  }, headers: headers

p JSON.parse(result)

URL obj = new URL("https://{environment}.masspay.io/{VERSION}/load/{user_token}");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("POST");
int responseCode = con.getResponseCode();
BufferedReader in = new BufferedReader(
    new InputStreamReader(con.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
    response.append(inputLine);
}
in.close();
System.out.println(response.toString());

POST /load/{user_token}

Initiate a load transaction

Initiates a load of funds into a user token's wallet.

Body parameter

{
  "client_load_id": "aEjn345",
  "source_token": "ba4275f2-bae1-488d-9d6f-20af1cd83574",
  "amount": 100.5,
  "source_currency_code": "USD",
  "notes": "Commission payment for July",
  "notify_user": true
}

Parameters

Name In Type Required Description
user_token path string true Token representing the user to load
Idempotency-Key header string false Unique key to prevent duplicate processing
body body LoadTxn true Load information

Example responses

200 Response

{
  "payout_token": "ba4275f2-bae1-488d-9d6f-20af1cd83574",
  "status": "success"
}

Responses

Status Meaning Description Schema
200 OK successful operation LoadTxnResp
403 Forbidden You do not have necessary permissions for the resource None
405 Method Not Allowed Invalid input None

getUserLoadsByToken

Code samples

# You can also use wget
curl -X GET https://{environment}.masspay.io/{VERSION}/load/{user_token} \
  -H 'Accept: application/json' \
  -H 'Idempotency-Key: string' \
  -H 'Authorization: Bearer {access-token}'

import requests
headers = {
  'Accept': 'application/json',
  'Idempotency-Key': 'string',
  'Authorization': 'Bearer {access-token}'
}

r = requests.get('https://{environment}.masspay.io/{VERSION}/load/{user_token}', params={

}, headers = headers)

print r.json()

require 'rest-client'
require 'json'

headers = {
  'Accept' => 'application/json',
  'Idempotency-Key' => 'string',
  'Authorization' => 'Bearer {access-token}'
}

result = RestClient.get 'https://{environment}.masspay.io/{VERSION}/load/{user_token}',
  params: {
  }, headers: headers

p JSON.parse(result)

URL obj = new URL("https://{environment}.masspay.io/{VERSION}/load/{user_token}");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("GET");
int responseCode = con.getResponseCode();
BufferedReader in = new BufferedReader(
    new InputStreamReader(con.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
    response.append(inputLine);
}
in.close();
System.out.println(response.toString());

GET /load/{user_token}

Get history of loads by user token

Gets a transaction history of all loads that were made to the provided user token.

Parameters

Name In Type Required Description
user_token path string true The user token that needs to be fetched.
Idempotency-Key header string false Unique key to prevent duplicate processing

Example responses

200 Response

[
  {
    "load_token": "ld_ba4275f2-bae1-488d-9d6f-20af1cd83574",
    "time_of_load": "2019-07-07T23:03:05",
    "client_load_id": "aEjn345",
    "source_token": "clnt_wlt_ba4275f2-bae1-488d-9d6f-20af1cd83574",
    "wallet_token": "usr_wlt_ba4275f2-bae1-488d-9d6f-20af1cd83574",
    "amount": 100.5,
    "source_currency_code": "USD",
    "notes": "Commission payment for July"
  }
]

Responses

Status Meaning Description Schema
200 OK successful operation Inline
400 Bad Request Invalid user token supplied None
404 Not Found User not found None

Response Schema

Status Code 200

Name Type Required Restrictions Description
anonymous [Loads] false none none
» load_token string true none Token representing the load token
» time_of_load string(YYYY-MM-DDThh:mm:ss) true none The timestamp the load was created in the system. Using UTC timestamp.ISO 8601
» client_load_id string true none A client defined load identifier. This is the unique ID assigned to the load on your system. Max 50 characters.
» source_token string(uuid) true none Token that represents the funding source i.e. bank account, wallet. 36 characters long
» wallet_token string(uuid) true none Token that represents the wallet that received the funds. 36 characters long
» amount number true none The amount to credit the user's wallet in source currency
» 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
» notes string true none A description for the load. Will be visible to the user receiving the load

Wallet

The wallet resource describes of a user's wallet.

getWallet

Code samples

# You can also use wget
curl -X GET https://{environment}.masspay.io/{VERSION}/wallet/{user_token} \
  -H 'Accept: application/json' \
  -H 'Idempotency-Key: string' \
  -H 'Authorization: Bearer {access-token}'

import requests
headers = {
  'Accept': 'application/json',
  'Idempotency-Key': 'string',
  'Authorization': 'Bearer {access-token}'
}

r = requests.get('https://{environment}.masspay.io/{VERSION}/wallet/{user_token}', params={

}, headers = headers)

print r.json()

require 'rest-client'
require 'json'

headers = {
  'Accept' => 'application/json',
  'Idempotency-Key' => 'string',
  'Authorization' => 'Bearer {access-token}'
}

result = RestClient.get 'https://{environment}.masspay.io/{VERSION}/wallet/{user_token}',
  params: {
  }, headers: headers

p JSON.parse(result)

URL obj = new URL("https://{environment}.masspay.io/{VERSION}/wallet/{user_token}");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("GET");
int responseCode = con.getResponseCode();
BufferedReader in = new BufferedReader(
    new InputStreamReader(con.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
    response.append(inputLine);
}
in.close();
System.out.println(response.toString());

GET /wallet/{user_token}

Retrieve all available wallets for a user

Retrieves all available wallets for a provided user token.

Parameters

Name In Type Required Description
user_token path string true Token representing the user who owns the wallet
Idempotency-Key header string false Unique key to prevent duplicate processing

Example responses

200 Response

[
  {
    "user_token": "usr_ba4275f2-bae1-488d-9d6f-20af1cd83574",
    "token": "usr_wlt_8bb3693f-2f98-43dd-a990-615b6a21596d",
    "balance": 100.5,
    "currency_code": "USD",
    "type": "USER_FUNDS",
    "card_type": "VISA",
    "last_4": 1234,
    "active": true
  }
]

Responses

Status Meaning Description Schema
200 OK successful operation Inline
403 Forbidden You do not have necessary permissions for the resource None
405 Method Not Allowed Invalid input Exception

Response Schema

Status Code 200

Name Type Required Restrictions Description
anonymous [WalletTxnResp] false none none
» user_token string true none Token representing the user
» token string(uuid) true none Token representing the wallet
» balance number true none The wallet's current balance in USD
» currency_code string true none The currency wallet balance is stored in. Using ISO 4217 format. In most cases this value will be USD
» type string true none Type of wallet
» card_type string false none In case type of wallet is MASSPAY_CARD, card_type would be provided with the type of card it is
» last_4 integer false none In case type of wallet is MASSPAY_CARD, last_4 would be provided with the last four digits of the card
» active boolean true none An indicator whether the wallet is active. If inactive, can still retrieve historical transactions history

Enumerated Values

Property Value
type MASSPAY_CARD
type USER_FUNDS
card_type MASTERCARD
card_type VISA
card_type AMEX
card_type DISCOVER
card_type UNIONPAY

getWalletCardInfo

Code samples

# You can also use wget
curl -X GET https://{environment}.masspay.io/{VERSION}/wallet/{user_token}/{wallet_token}/card \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer {access-token}'

import requests
headers = {
  'Accept': 'application/json',
  'Authorization': 'Bearer {access-token}'
}

r = requests.get('https://{environment}.masspay.io/{VERSION}/wallet/{user_token}/{wallet_token}/card', params={

}, headers = headers)

print r.json()

require 'rest-client'
require 'json'

headers = {
  'Accept' => 'application/json',
  'Authorization' => 'Bearer {access-token}'
}

result = RestClient.get 'https://{environment}.masspay.io/{VERSION}/wallet/{user_token}/{wallet_token}/card',
  params: {
  }, headers: headers

p JSON.parse(result)

URL obj = new URL("https://{environment}.masspay.io/{VERSION}/wallet/{user_token}/{wallet_token}/card");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("GET");
int responseCode = con.getResponseCode();
BufferedReader in = new BufferedReader(
    new InputStreamReader(con.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
    response.append(inputLine);
}
in.close();
System.out.println(response.toString());

GET /wallet/{user_token}/{wallet_token}/card

Get MassPay Card Information

Retrieves MassPay card information that is associated with the provided wallet token

Parameters

Name In Type Required Description
user_token path string true Token representing the user who owns the wallet
wallet_token path string(uuid) true Token representing the wallet

Example responses

200 Response

{
  "card_number": 4016483301928344,
  "cvv": "123",
  "expiration_date": "2020-09-11",
  "pin_number": "1234",
  "balance": 103,
  "type": "VISA",
  "status": "ACTIVE"
}

Responses

Status Meaning Description Schema
200 OK OK Inline
403 Forbidden Forbidden None
405 Method Not Allowed Method not allowes Exception

Response Schema

Status Code 200

MassPay Card Information

Name Type Required Restrictions Description
» card_number integer true none 16 Digits card number
» cvv string true none 3 Digits cvv code
» expiration_date string(date) true none Card expiration date
» pin_number string true none Card pin number (used in ATM machines)
» balance number(float) true none Available balance on the card
» type string true none Card type
» status string true none Status of the card

Enumerated Values

Property Value
type VISA
type MASTERCARD
type DISCOVER
type AMEX
type UNIONPAY
status ACTIVE
status INACTIVE
status CLOSED

Attribute

The attribute resource describes attributes of a user. For instance their bank account number, ID number, DOB, etc.

storeAttrs

Code samples

# You can also use wget
curl -X POST https://{environment}.masspay.io/{VERSION}/attribute/{user_token}/{destination_token} \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'Idempotency-Key: string' \
  -H 'Authorization: Bearer {access-token}'

import requests
headers = {
  'Content-Type': 'application/json',
  'Accept': 'application/json',
  'Idempotency-Key': 'string',
  'Authorization': 'Bearer {access-token}'
}

r = requests.post('https://{environment}.masspay.io/{VERSION}/attribute/{user_token}/{destination_token}', params={

}, headers = headers)

print r.json()

require 'rest-client'
require 'json'

headers = {
  'Content-Type' => 'application/json',
  'Accept' => 'application/json',
  'Idempotency-Key' => 'string',
  'Authorization' => 'Bearer {access-token}'
}

result = RestClient.post 'https://{environment}.masspay.io/{VERSION}/attribute/{user_token}/{destination_token}',
  params: {
  }, headers: headers

p JSON.parse(result)

URL obj = new URL("https://{environment}.masspay.io/{VERSION}/attribute/{user_token}/{destination_token}");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("POST");
int responseCode = con.getResponseCode();
BufferedReader in = new BufferedReader(
    new InputStreamReader(con.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
    response.append(inputLine);
}
in.close();
System.out.println(response.toString());

POST /attribute/{user_token}/{destination_token}

Store user attributes

If existing attributes are already stored, this call will override its values.

Body parameter

{
  "values": [
    {
      "token": "e2ca24e9-c546-4c64-90d2-cb8e70e7c9ba",
      "value": "432532532"
    }
  ],
  "attr_set_token": "attr_set_e2ca24e9-c546-4c64-90d2-cb8e70e7c9ba"
}

Parameters

Name In Type Required Description
user_token path string true Token representing the user to store attributes for
destination_token path string true Token that represents the payout destination i.e. Omnex->Brazil->Bank Deposit->Itau. To be retrieved from the #pricing callback.
Idempotency-Key header string false Unique key to prevent duplicate processing
body body AttrTxn true Attr parameters to store

Example responses

405 Response

{
  "Exception": "string",
  "Errors": [
    "string"
  ]
}

Responses

Status Meaning Description Schema
200 OK successful operation None
403 Forbidden You do not have necessary permissions for the resource None
405 Method Not Allowed Invalid input Exception

getAttrs

Code samples

# You can also use wget
curl -X GET https://{environment}.masspay.io/{VERSION}/attribute/{user_token}/{destination_token} \
  -H 'Accept: application/json' \
  -H 'Idempotency-Key: string' \
  -H 'Authorization: Bearer {access-token}'

import requests
headers = {
  'Accept': 'application/json',
  'Idempotency-Key': 'string',
  'Authorization': 'Bearer {access-token}'
}

r = requests.get('https://{environment}.masspay.io/{VERSION}/attribute/{user_token}/{destination_token}', params={

}, headers = headers)

print r.json()

require 'rest-client'
require 'json'

headers = {
  'Accept' => 'application/json',
  'Idempotency-Key' => 'string',
  'Authorization' => 'Bearer {access-token}'
}

result = RestClient.get 'https://{environment}.masspay.io/{VERSION}/attribute/{user_token}/{destination_token}',
  params: {
  }, headers: headers

p JSON.parse(result)

URL obj = new URL("https://{environment}.masspay.io/{VERSION}/attribute/{user_token}/{destination_token}");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("GET");
int responseCode = con.getResponseCode();
BufferedReader in = new BufferedReader(
    new InputStreamReader(con.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
    response.append(inputLine);
}
in.close();
System.out.println(response.toString());

GET /attribute/{user_token}/{destination_token}

Get user attributes for destination_token

Get all the required attributes for the provided user for a prticular destination token. If any of the attributes already have a stored value, it will be returned as well.

Parameters

Name In Type Required Description
user_token path string true Token representing the user to retrieve attributes for
destination_token path string true Token that represents the payout destination i.e. Omnex->Brazil->Bank Deposit->Itau. To be retrieved from the #pricing callback.
Idempotency-Key header string false Unique key to prevent duplicate processing

Example responses

200 Response

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

Responses

Status Meaning Description Schema
200 OK successful operation Inline
403 Forbidden You do not have necessary permissions for the resource None
405 Method Not Allowed Invalid input Exception

Response Schema

Status Code 200

Name Type Required Restrictions Description
anonymous [AttrsRequirement] false none none
» token string true none The token that represents the attribute.
» attr_set_token string false none The token that represents the stored attributes for this payer. You would use this token in attr_set_token of initiatePayout if you have to specify an account number when paying a transaction out.
» label string false none The label that describes that required attribute
» validation string false none RegEx that validates that input
» is_optional boolean false none Flag to indicate whether this field is required or not
» value string true none The existing value that is stored. 'Null' if no existing value is stored.
» expected_value string false none Written explanation of the value that the regex validation requires
» type string false none The type of attribute

Enumerated Values

Property Value
type CardNumber
type BankAccountType
type BankAccountNumber
type BankAccountBranchNumber
type BankName
type PhoneNumber
type Gender
type IdentificationNumber
type BillReferenceNumber
type BankRoutingNumber
type BankAccountName
type MaidenName
type SocialSecurity
type EmploymentName
type EmploymentAddress
type EmploymentPhone
type EmploymentOccupation
type EmploymentSupervisor
type RemittanceReason
type Relationship
type SecondLastName
type SWIFT
type BirthCountry
type SourceOfFunds
type DateOfBirth

Account

The account resource describes your account.

getAccountBalance

Code samples

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

import requests
headers = {
  'Accept': 'application/json',
  'Authorization': 'Bearer {access-token}'
}

r = requests.get('https://{environment}.masspay.io/{VERSION}/account/balance', params={

}, headers = headers)

print r.json()

require 'rest-client'
require 'json'

headers = {
  'Accept' => 'application/json',
  'Authorization' => 'Bearer {access-token}'
}

result = RestClient.get 'https://{environment}.masspay.io/{VERSION}/account/balance',
  params: {
  }, headers: headers

p JSON.parse(result)

URL obj = new URL("https://{environment}.masspay.io/{VERSION}/account/balance");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("GET");
int responseCode = con.getResponseCode();
BufferedReader in = new BufferedReader(
    new InputStreamReader(con.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
    response.append(inputLine);
}
in.close();
System.out.println(response.toString());

GET /account/balance

Get current available balance

Retrieves the current available balances.

Example responses

200 Response

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

Responses

Status Meaning Description Schema
200 OK successful operation Inline
403 Forbidden You do not have necessary permissions for the resource None
405 Method Not Allowed Invalid input None

Response Schema

Status Code 200

Name Type Required Restrictions Description
anonymous [AvailableBalanceTxnResp] false none none
» token string true none Token representing your funding account. You should use this as source_token when paying out transactions.
» balance number true none Your account's current available balance in USD
» currency_code string true none The currency the balance is stored in. Using ISO 4217 format. In most cases this value will be USD

Catalog

The catalog resource describes the available services and countries.

getCountryList

Code samples

# You can also use wget
curl -X GET https://{environment}.masspay.io/{VERSION}/country/list \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer {access-token}'

import requests
headers = {
  'Accept': 'application/json',
  'Authorization': 'Bearer {access-token}'
}

r = requests.get('https://{environment}.masspay.io/{VERSION}/country/list', params={

}, headers = headers)

print r.json()

require 'rest-client'
require 'json'

headers = {
  'Accept' => 'application/json',
  'Authorization' => 'Bearer {access-token}'
}

result = RestClient.get 'https://{environment}.masspay.io/{VERSION}/country/list',
  params: {
  }, headers: headers

p JSON.parse(result)

URL obj = new URL("https://{environment}.masspay.io/{VERSION}/country/list");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("GET");
int responseCode = con.getResponseCode();
BufferedReader in = new BufferedReader(
    new InputStreamReader(con.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
    response.append(inputLine);
}
in.close();
System.out.println(response.toString());

GET /country/list

Gets a list of countries where services offered.

Get a list of all currently available countries of service.

Example responses

200 Response

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

Responses

Status Meaning Description Schema
200 OK successful operation Inline
403 Forbidden You do not have necessary permissions for the resource None
405 Method Not Allowed Invalid input None

Response Schema

Status Code 200

Name Type Required Restrictions Description
anonymous [Country] false none none
» code string true none Country code ISO_3166
» name string true none Name of country

getCountryServices

Code samples

# You can also use wget
curl -X GET https://{environment}.masspay.io/{VERSION}/country/{country_code} \
  -H 'Accept: application/json' \
  -H 'Idempotency-Key: string' \
  -H 'Authorization: Bearer {access-token}'

import requests
headers = {
  'Accept': 'application/json',
  'Idempotency-Key': 'string',
  'Authorization': 'Bearer {access-token}'
}

r = requests.get('https://{environment}.masspay.io/{VERSION}/country/{country_code}', params={

}, headers = headers)

print r.json()

require 'rest-client'
require 'json'

headers = {
  'Accept' => 'application/json',
  'Idempotency-Key' => 'string',
  'Authorization' => 'Bearer {access-token}'
}

result = RestClient.get 'https://{environment}.masspay.io/{VERSION}/country/{country_code}',
  params: {
  }, headers: headers

p JSON.parse(result)

URL obj = new URL("https://{environment}.masspay.io/{VERSION}/country/{country_code}");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("GET");
int responseCode = con.getResponseCode();
BufferedReader in = new BufferedReader(
    new InputStreamReader(con.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
    response.append(inputLine);
}
in.close();
System.out.println(response.toString());

GET /country/{country_code}

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
user_token query string(uuid) false Token representing a user. If provided, the results would be custom-tailored to this user.
include_payer_logos query boolean false Whether to include the payers logo in base64 format.

Example responses

200 Response

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

Responses

Status Meaning Description Schema
200 OK successful operation CompaniesResp
403 Forbidden You do not have necessary permissions for the resource None
405 Method Not Allowed Invalid input None

getUserAgreement

Code samples

# You can also use wget
curl -X GET https://{environment}.masspay.io/{VERSION}/user-agreements?id=2 \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer {access-token}'

import requests
headers = {
  'Accept': 'application/json',
  'Authorization': 'Bearer {access-token}'
}

r = requests.get('https://{environment}.masspay.io/{VERSION}/user-agreements', params={
  'id': '2'
}, headers = headers)

print r.json()

require 'rest-client'
require 'json'

headers = {
  'Accept' => 'application/json',
  'Authorization' => 'Bearer {access-token}'
}

result = RestClient.get 'https://{environment}.masspay.io/{VERSION}/user-agreements',
  params: {
  'id' => 'integer'
}, headers: headers

p JSON.parse(result)

URL obj = new URL("https://{environment}.masspay.io/{VERSION}/user-agreements?id=2");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("GET");
int responseCode = con.getResponseCode();
BufferedReader in = new BufferedReader(
    new InputStreamReader(con.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
    response.append(inputLine);
}
in.close();
System.out.println(response.toString());

GET /user-agreements

Get User Agreement

Get available user agreements for payout services

Parameters

Name In Type Required Description
id query integer true Id representing user agreement (retrieved from OPTIONS call)

Example responses

200 Response

{
  "name": "MassPay Card Program - USD",
  "content": "string",
  "last_modified": "2020-07-21T17:32:28Z",
  "id": 2,
  "mime_type": "application/pdf"
}

Responses

Status Meaning Description Schema
200 OK successful operation Inline
403 Forbidden You do not have necessary permissions for the resource None
405 Method Not Allowed Invalid input None

Response Schema

Status Code 200

User Agreement

Name Type Required Restrictions Description
» name string true none Name of user agreement
» content string(byte) true none Base64 encoded byte representing the content of the file
» last_modified string(date-time) true none Time when the agreement was last updated
» id integer true none Id representing the user agreement
» mime_type string false none Mime type of the user agreement (i.e application/pdf)

getUserAgreementsNames

Code samples

# You can also use wget
curl -X OPTIONS https://{environment}.masspay.io/{VERSION}/user-agreements \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer {access-token}'

import requests
headers = {
  'Accept': 'application/json',
  'Authorization': 'Bearer {access-token}'
}

r = requests.options('https://{environment}.masspay.io/{VERSION}/user-agreements', params={

}, headers = headers)

print r.json()

require 'rest-client'
require 'json'

headers = {
  'Accept' => 'application/json',
  'Authorization' => 'Bearer {access-token}'
}

result = RestClient.options 'https://{environment}.masspay.io/{VERSION}/user-agreements',
  params: {
  }, headers: headers

p JSON.parse(result)

URL obj = new URL("https://{environment}.masspay.io/{VERSION}/user-agreements");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("OPTIONS");
int responseCode = con.getResponseCode();
BufferedReader in = new BufferedReader(
    new InputStreamReader(con.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
    response.append(inputLine);
}
in.close();
System.out.println(response.toString());

OPTIONS /user-agreements

Get Available User Agreements

Get available user agreements for payout services (without content)

Example responses

200 Response

[
  {
    "name": "MassPay Card Program - USD",
    "last_modified": "2020-07-21T17:32:28Z",
    "id": 2,
    "mime_type": "application/pdf"
  }
]

Responses

Status Meaning Description Schema
200 OK successful operation Inline
403 Forbidden You do not have necessary permissions for the resource None
405 Method Not Allowed Invalid input None

Response Schema

Status Code 200

List of user agreements

Name Type Required Restrictions Description
» name string true none Name of user agreement
» last_modified string(date-time) true none Time when the agreement was last updated
» id integer true none Id representing the user agreement (to be used to retrieve it)
» mime_type string true none Mime type of the user agreement (i.e application/pdf)

Spend Back

The spend back resource describes a spend bank from the user's wallet

getUserSpendbacksByToken

Code samples

# You can also use wget
curl -X GET https://{environment}.masspay.io/{VERSION}/spendback/{user_token} \
  -H 'Accept: application/json' \
  -H 'Idempotency-Key: string' \
  -H 'Authorization: Bearer {access-token}'

import requests
headers = {
  'Accept': 'application/json',
  'Idempotency-Key': 'string',
  'Authorization': 'Bearer {access-token}'
}

r = requests.get('https://{environment}.masspay.io/{VERSION}/spendback/{user_token}', params={

}, headers = headers)

print r.json()

require 'rest-client'
require 'json'

headers = {
  'Accept' => 'application/json',
  'Idempotency-Key' => 'string',
  'Authorization' => 'Bearer {access-token}'
}

result = RestClient.get 'https://{environment}.masspay.io/{VERSION}/spendback/{user_token}',
  params: {
  }, headers: headers

p JSON.parse(result)

URL obj = new URL("https://{environment}.masspay.io/{VERSION}/spendback/{user_token}");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("GET");
int responseCode = con.getResponseCode();
BufferedReader in = new BufferedReader(
    new InputStreamReader(con.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
    response.append(inputLine);
}
in.close();
System.out.println(response.toString());

GET /spendback/{user_token}

Get history of spend backs by user token

Gets a list of all historical spendbacks for a provided user token.

Parameters

Name In Type Required Description
Idempotency-Key header string false Unique key to prevent duplicate processing
user_token path string true Token representing the user to fetch/initiate spend back

Example responses

200 Response

[
  {
    "spendback_token": "spnd_bk_4275f2-bae1-488d-9d6f-20af1cd83574",
    "time_of_spendback": "2019-07-07T23:03:05",
    "client_spendback_id": "aEjn345",
    "source_token": "usr_wlt_ba4275f2-bae1-488d-9d6f-20af1cd83574",
    "wallet_token": "clnt_wlt_ba4275f2-bae1-488d-9d6f-20af1cd83574",
    "amount": 100.5,
    "source_currency_code": "USD",
    "notes": "Commission payment for July"
  }
]

Responses

Status Meaning Description Schema
200 OK OK Inline

Response Schema

Status Code 200

Name Type Required Restrictions Description
anonymous [SpendBacks] false none none
» spendback_token string true none Token representing the load token
» time_of_spendback string(YYYY-MM-DDThh:mm:ss) true none The timestamp the spend back was created in the system. Using UTC timestamp.ISO 8601
» client_spendback_id string true none A client defined spend back identifier. This is the unique ID assigned to the spend back on your system. Max 50 characters.
» source_token string(uuid) true none Token that represents the funding source i.e. bank account, wallet. 36 characters long
» wallet_token string(uuid) true none Token that represents the wallet that received the funds. 36 characters long
» amount number true none The amount to credit the user's wallet in source currency
» 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
» notes string true none A description for the load. Will be visible to the user receiving the load

initiateSpendback

Code samples

# You can also use wget
curl -X POST https://{environment}.masspay.io/{VERSION}/spendback/{user_token} \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'Idempotency-Key: string' \
  -H 'Authorization: Bearer {access-token}'

import requests
headers = {
  'Content-Type': 'application/json',
  'Accept': 'application/json',
  'Idempotency-Key': 'string',
  'Authorization': 'Bearer {access-token}'
}

r = requests.post('https://{environment}.masspay.io/{VERSION}/spendback/{user_token}', params={

}, headers = headers)

print r.json()

require 'rest-client'
require 'json'

headers = {
  'Content-Type' => 'application/json',
  'Accept' => 'application/json',
  'Idempotency-Key' => 'string',
  'Authorization' => 'Bearer {access-token}'
}

result = RestClient.post 'https://{environment}.masspay.io/{VERSION}/spendback/{user_token}',
  params: {
  }, headers: headers

p JSON.parse(result)

URL obj = new URL("https://{environment}.masspay.io/{VERSION}/spendback/{user_token}");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("POST");
int responseCode = con.getResponseCode();
BufferedReader in = new BufferedReader(
    new InputStreamReader(con.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
    response.append(inputLine);
}
in.close();
System.out.println(response.toString());

POST /spendback/{user_token}

Initiate a spend back transaction

Initiates a spend back transaction to a provided user token.

Body parameter

{
  "client_spendback_id": "aEjn345",
  "source_token": "usr_wlt_d2138fd0-00be-45a8-985f-4f5bff500962",
  "source_currency_code": "USD",
  "amount": 100.5,
  "notes": "Purchase of Candles. Order #14930"
}

Parameters

Name In Type Required Description
Idempotency-Key header string false Unique key to prevent duplicate processing
body body SpendBackTxn false Spend back information
user_token path string true Token representing the user to fetch/initiate spend back

Example responses

200 Response

{
  "spendback_token": "spnd_bk_d2138fd0-00be-45a8-985f-4f5bff5e3962",
  "client_spendback_id": "aEjn345",
  "status": "success"
}

Responses

Status Meaning Description Schema
200 OK OK SpendBackTxnResp

Card

The card resource describe your MassPay cards

updateWalletCardInfo

Code samples

# You can also use wget
curl -X PUT https://{environment}.masspay.io/{VERSION}/wallet/{user_token}/{wallet_token}/card \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer {access-token}'

import requests
headers = {
  'Accept': 'application/json',
  'Authorization': 'Bearer {access-token}'
}

r = requests.put('https://{environment}.masspay.io/{VERSION}/wallet/{user_token}/{wallet_token}/card', params={

}, headers = headers)

print r.json()

require 'rest-client'
require 'json'

headers = {
  'Accept' => 'application/json',
  'Authorization' => 'Bearer {access-token}'
}

result = RestClient.put 'https://{environment}.masspay.io/{VERSION}/wallet/{user_token}/{wallet_token}/card',
  params: {
  }, headers: headers

p JSON.parse(result)

URL obj = new URL("https://{environment}.masspay.io/{VERSION}/wallet/{user_token}/{wallet_token}/card");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("PUT");
int responseCode = con.getResponseCode();
BufferedReader in = new BufferedReader(
    new InputStreamReader(con.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
    response.append(inputLine);
}
in.close();
System.out.println(response.toString());

PUT /wallet/{user_token}/{wallet_token}/card

Update MassPay Card Information

Update card pin number or/and status

Parameters

Name In Type Required Description
pin query string false New 4 digit pin number for the card (To be used in ATM machines)
status query string false New status for the card
user_token path string true Token representing the user who owns the wallet
wallet_token path string(uuid) true Token representing the wallet

Enumerated Values

Parameter Value
status CLOSED
status SUSPEND
status UNSUSPEND

Example responses

405 Response

{
  "Exception": "string",
  "Errors": [
    "string"
  ]
}

Responses

Status Meaning Description Schema
200 OK OK None
403 Forbidden Forbidden None
405 Method Not Allowed Method Not Allowed Exception

Schemas

User

{
  "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": "jdoe@gmail.com",
  "language": "en",
  "mobile_number": "16502000226",
  "business_name": "ABC Company"
}

Properties

Name Type Required Restrictions Description
internal_user_id string true none A client-defined identifier for the user. This is the unique ID assigned to the user on your system. Max 75 characters. Allows letters, numbers, and + , - . / _ ~
address1 string false none The user's street address.
address2 string false none The user's street address, line 2.
city string false none The user's city.
state_province string false none The user's state/province.
postal_code string false none The user's postal code.
country string false none The user's country code. ISO_3166 code
first_name string true none The user's first name. (If Business account, the first name of the representative)
middle_name string false none The user's middle name. (If Business account, the middle name of the representative)
last_name string true none The user's last name. (If Business account, the last name of the representative)
email string true none The user's e-mail address. Must be unique. Cannot have two users with the same e-mail address.
language string false none The user's preferred language of communication. If not provided, defaults to English (en)
mobile_number string false none (Optional) Mobile number of user. Allows for SMS notifications upon availability of funds
business_name string false none Company legal name (Only if Business account)

Loads

{
  "load_token": "ld_ba4275f2-bae1-488d-9d6f-20af1cd83574",
  "time_of_load": "2019-07-07T23:03:05",
  "client_load_id": "aEjn345",
  "source_token": "clnt_wlt_ba4275f2-bae1-488d-9d6f-20af1cd83574",
  "wallet_token": "usr_wlt_ba4275f2-bae1-488d-9d6f-20af1cd83574",
  "amount": 100.5,
  "source_currency_code": "USD",
  "notes": "Commission payment for July"
}

Properties

Name Type Required Restrictions Description
load_token string true none Token representing the load token
time_of_load string(YYYY-MM-DDThh:mm:ss) true none The timestamp the load was created in the system. Using UTC timestamp.ISO 8601
client_load_id string true none A client defined load identifier. This is the unique ID assigned to the load on your system. Max 50 characters.
source_token string(uuid) true none Token that represents the funding source i.e. bank account, wallet. 36 characters long
wallet_token string(uuid) true none Token that represents the wallet that received the funds. 36 characters long
amount number true none The amount to credit the user's wallet in source currency
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
notes string true none A description for the load. Will be visible to the user receiving the load

StoredUser

{
  "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": "jdoe@gmail.com",
  "language": "en",
  "mobile_number": "16502000226",
  "business_name": "ABC Company"
}

Properties

Name Type Required Restrictions Description
user_token string(uuid) true none Token representing the user that was just created
status string true none The status of the user
created_on string(YYYY-MM-DDThh:mm:ss) true none The timestamp the user was created in the system. Using UTC timestamp.ISO 8601
internal_user_id string true none A client-defined identifier for the user. This is the unique ID assigned to the user on your system. Max 75 characters. Allows letters, numbers, and + , - . / _ ~
address1 string false none The user's street address.
address2 string false none The user's street address, line 2.
city string false none The user's city.
state_province string false none The user's state/province.
postal_code string false none The user's postal code.
country string false none The user's country code. ISO_3166-1_alpha-3 code
first_name string true none The user's first name. (If Business account, the first name of the representative)
middle_name string false none The user's middle name. (If Business account, the middle name of the representative)
last_name string true none The user's last name. (If Business account, the last name of the representative)
email string true none The user's e-mail address. Must be unique. Cannot have two users with the same e-mail address.
language string false none The user's preferred language of communication. If not provided, defaults to English (en)
mobile_number string false none (Optional) Mobile number of user. Allows for SMS notifications upon availability of funds
business_name string false none Company legal name (Only if Business account)

Enumerated Values

Property Value
status ACTIVE
status LOCKED
status DEACTIVE

UpdateUser

{
  "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": "jdoe@gmail.com",
  "language": "en",
  "mobile_number": "16502000226"
}

Properties

Name Type Required Restrictions Description
status string true none The status of the user, if set to ACTIVE when current status is DEACTIVE, reactivation fee will incur
created_on string(YYYY-MM-DDThh:mm:ss) false none The timestamp the user was created in the system. Using UTC timestamp.ISO 8601
internal_user_id string true none A client-defined identifier for the user. This is the unique ID assigned to the user on your system. Max 75 characters. Allows letters, numbers, and + , - . / _ ~
address1 string true none The user's street address.
address2 string false none The user's street address, line 2.
city string true none The user's city.
state_province string true none The user's state/province.
postal_code string true none The user's postal code.
country string true none The user's country code. ISO_3166-1_alpha-3 code
first_name string true none The user's first name.
middle_name string false none The user's middle name.
last_name string true none The user's last name.
email string true none The user's e-mail address. Must be unique. Cannot have two users with the same e-mail address.
language string false none The user's preferred language of communication. If not provided, defaults to English (en)
mobile_number string false none (Optional) Mobile number of user. Allows for SMS notifications upon availability of funds

Enumerated Values

Property Value
status ACTIVE
status DEACTIVE

WalletTxnResp

{
  "user_token": "usr_ba4275f2-bae1-488d-9d6f-20af1cd83574",
  "token": "usr_wlt_8bb3693f-2f98-43dd-a990-615b6a21596d",
  "balance": 100.5,
  "currency_code": "USD",
  "type": "USER_FUNDS",
  "card_type": "VISA",
  "last_4": 1234,
  "active": true
}

Properties

Name Type Required Restrictions Description
user_token string true none Token representing the user
token string(uuid) true none Token representing the wallet
balance number true none The wallet's current balance in USD
currency_code string true none The currency wallet balance is stored in. Using ISO 4217 format. In most cases this value will be USD
type string true none Type of wallet
card_type string false none In case type of wallet is MASSPAY_CARD, card_type would be provided with the type of card it is
last_4 integer false none In case type of wallet is MASSPAY_CARD, last_4 would be provided with the last four digits of the card
active boolean true none An indicator whether the wallet is active. If inactive, can still retrieve historical transactions history

Enumerated Values

Property Value
type MASSPAY_CARD
type USER_FUNDS
card_type MASTERCARD
card_type VISA
card_type AMEX
card_type DISCOVER
card_type UNIONPAY

AvailableBalanceTxnResp

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

Properties

Name Type Required Restrictions Description
token string true none Token representing your funding account. You should use this as source_token when paying out transactions.
balance number true none Your account's current available balance in USD
currency_code string true none The currency the balance is stored in. Using ISO 4217 format. In most cases this value will be USD

AttrTxn

{
  "values": [
    {
      "token": "e2ca24e9-c546-4c64-90d2-cb8e70e7c9ba",
      "value": "432532532"
    }
  ],
  "attr_set_token": "attr_set_e2ca24e9-c546-4c64-90d2-cb8e70e7c9ba"
}

Properties

Name Type Required Restrictions Description
values [AttrValue] true none none
attr_set_token string false none The token that represents a set of attributes for a specific payer. Optional, specify the value if you're trying to update a value of a specific attributes set.

AttrValue

{
  "token": "e2ca24e9-c546-4c64-90d2-cb8e70e7c9ba",
  "value": "432532532"
}

Properties

Name Type Required Restrictions Description
token string true none The token that represents the attribute that needs to be updated.
value string true none The value that needs to be stored for the associated token

AttrsRequirement

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

Properties

Name Type Required Restrictions Description
token string true none The token that represents the attribute.
attr_set_token string false none The token that represents the stored attributes for this payer. You would use this token in attr_set_token of initiatePayout if you have to specify an account number when paying a transaction out.
label string false none The label that describes that required attribute
validation string false none RegEx that validates that input
is_optional boolean false none Flag to indicate whether this field is required or not
value string true none The existing value that is stored. 'Null' if no existing value is stored.
expected_value string false none Written explanation of the value that the regex validation requires
type string false none The type of attribute

Enumerated Values

Property Value
type CardNumber
type BankAccountType
type BankAccountNumber
type BankAccountBranchNumber
type BankName
type PhoneNumber
type Gender
type IdentificationNumber
type BillReferenceNumber
type BankRoutingNumber
type BankAccountName
type MaidenName
type SocialSecurity
type EmploymentName
type EmploymentAddress
type EmploymentPhone
type EmploymentOccupation
type EmploymentSupervisor
type RemittanceReason
type Relationship
type SecondLastName
type SWIFT
type BirthCountry
type SourceOfFunds
type DateOfBirth

LoadTxn

{
  "client_load_id": "aEjn345",
  "source_token": "ba4275f2-bae1-488d-9d6f-20af1cd83574",
  "amount": 100.5,
  "source_currency_code": "USD",
  "notes": "Commission payment for July",
  "notify_user": true
}

Properties

Name Type Required Restrictions Description
client_load_id string true none A client defined load identifier. This is the unique ID assigned to the load on your system. Max 50 characters.
source_token string(uuid) true none Token that represents the funding source i.e. bank account, wallet. 36 characters long
amount number true none The amount to credit the user's wallet in source currency
source_currency_code string false 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
notes string false none A description for the load. Will be visible to the user receiving the load
notify_user boolean false none Should we notify the user via email that they've received a load? If the user has no existing account, they will receive instructions to establish such account.

LoadTxnResp

{
  "payout_token": "ba4275f2-bae1-488d-9d6f-20af1cd83574",
  "status": "success"
}

Properties

Name Type Required Restrictions Description
payout_token string(uuid) true none Token that represents the load 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.

Enumerated Values

Property Value
status success
status failure

PayoutTxn

{
  "client_transfer_id": "aEjn345",
  "source_currency_code": "USD",
  "destination_currency_code": "MXN",
  "source_token": "usr_wlt_ba4275f2-bae1-488d-9d6f-20af1cd83574",
  "destination_token": "dest_d2138fd0-00be-45a8-985f-4f5bde500962",
  "destination_amount": 100.5,
  "source_amount": 100.5,
  "attr_set_token": "attr_set_b1a867c1-6e36-4525-b6d5-a20bac80e3b0"
}

Properties

Name Type Required Restrictions Description
client_transfer_id string false none A client defined transfer identifier. This is the unique ID assigned to the transfer on your system. Max 50 characters.
source_currency_code string false 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
destination_currency_code string true none The currency the funds will be deposited into. Using ISO 4217 format
source_token string(uuid) true none Token that represents the funding source i.e. bank account, wallet. 36 characters long
destination_token string(uuid) true none 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

PayoutTxnResp

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

Properties

Name Type Required Restrictions Description
payout_token string(uuid) true none Token that represents the transaction that was just created. Need to be used to commit the transaction in /payout/{user_token}/{payout_token}. Value would be NSF if there are not enough funds in the source_token. Value would be DUPLICATE if there is a duplicate client_transfer_id.
client_transfer_id string true none A client defined transfer identifier. This is the unique ID assigned to the transfer on your system. Max 50 characters.
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
destination_currency_code string true none The currency the funds will be deposited into. Using ISO 4217 format
source_token string(uuid) true none Token that represents the funding source i.e. your bank account, user's wallet. 36 characters long
destination_token string(uuid) true none 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.
status string true none The status of the transaction
payer_logo string(byte) false none base64 representation of the payer logo
payer_name string false none Name of payer
delivery_type string false none none
country_code string false none Country code ISO_3166

Enumerated Values

Property Value
status PENDING
status PROCESSING
status COMPLETED
status CANCELLED
status READY_FOR_PICKUP
status HOLD
status ERROR
delivery_type CASH_PICKUP
delivery_type BANK_DEPOSIT
delivery_type HOME_DELIVERY
delivery_type MOBILE_WALLET
delivery_type MASSPAY_CARD

PayoutTxnCommitResp

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

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

Name Type Required Restrictions Description
code string true none Country code ISO_3166
name string true none Name of country

CompaniesResp

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

Properties

Name Type Required Restrictions Description
companies [Company] true none none

Company

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

Properties

Name Type Required Restrictions Description
company_logo string(byte) true none base64 representation of the company logo
services [Service] true none none
rating number true none Overall rating of provider calculated from feedback provided by users from previous trasnactions
description string true none A short description of the company
company_name string true none The company name

Service

{
  "country_code": "MX",
  "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"
    }
  ]
}

Properties

Name Type Required Restrictions Description
country_code string true none Country code ISO_3166
delivery_type string true none The type of service. I.e. cash pickup, home delivery, etc.
payers [object] true none none
» destination_token string(uuid) true none Token that represents the payout destination. 36 characters long
» payer_logo string(byte) true none base64 representation of the payer logo
» payer_name string true none Name of payer
» exchange_rate [object] true none Lists all available currencies and their estimated rates
»» currency_symbol string true none Using ISO 4217 format.
»» exchange_rate number(double) true none Estimated rate
» fee number(double) true none Service fee
» max_limit number(double) true none The maximum amount the user can send with this service. 0 if no upper limit
» min_limit number(double) true none The minimum amount the user can send with this service. 0 if no lower limit
» source_amount number(double) false none Optional return field. Will only show if limit parameter is provided
» number_of_locations integer(int32) false none Total number of locations. Mostly relevant for cash pickup services. 0 if unknown or irrelevant
» estimated_availability string(date-time) false none Estimated availability of funds. When funds would be available to pickup/deposited

Enumerated Values

Property Value
delivery_type CASH_PICKUP
delivery_type BANK_DEPOSIT
delivery_type HOME_DELIVERY
delivery_type MOBILE_WALLET
delivery_type MASSPAY_CARD

ApiResponse

{
  "code": 0,
  "type": "string",
  "message": "string"
}

Properties

Name Type Required Restrictions Description
code integer(int32) false none none
type string false none none
message string false none none

FoundUser

{
  "user_token": "usr_f4741aa2-9f39-4358-8247-2409e3fc2715",
  "first_name": "string",
  "last_name": "string"
}

FoundUser

Properties

Name Type Required Restrictions Description
user_token string true none The token of the found user
first_name string true none First name of the user
last_name string true none Last name of the user

SpendBackTxnResp

{
  "spendback_token": "spnd_bk_d2138fd0-00be-45a8-985f-4f5bff5e3962",
  "client_spendback_id": "aEjn345",
  "status": "success"
}

SpendBackTxnResp

Properties

Name Type Required Restrictions Description
spendback_token string(uuid) true none Token that represents the spend back that was just created.
client_spendback_id string true none A client defined spend back identifier. This is the unique ID assigned to the load on your system. Max 50 characters.
status string true none Status that indicates whether the transaction was successfully processed. If success, everything was processed correctly. failure indicates a generic error.

Enumerated Values

Property Value
status success
status failure

SpendBackTxn

{
  "client_spendback_id": "aEjn345",
  "source_token": "usr_wlt_d2138fd0-00be-45a8-985f-4f5bff500962",
  "source_currency_code": "USD",
  "amount": 100.5,
  "notes": "Purchase of Candles. Order #14930"
}

SpendBackTxn

Properties

Name Type Required Restrictions Description
client_spendback_id string true none A client defined spend back identifier. This is the unique ID assigned to the load on your system. Max 50 characters.
source_token string(uuid) true none Token that represents the funding source i.e. bank account, wallet. 36 characters long
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
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": "payout_d2138fd0-00be-45a8-985f-4f5b87500962",
  "type": "payout",
  "time_of_txn": "2020-09-11T04:07:10Z",
  "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",
  "source_token": "usr_wlt_ba4275f2-bae1-488d-9d6f-20af1cd83574",
  "destination_token": "dest_d2138fd0-00be-45a8-985f-4f5bde500962",
  "delivery_type": "CASH_PICKUP"
}

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
destination_amount number(float) true none The amount that was received in destination_currency_code
destination_currency_code string true none The currency of the funds received. Using ISO 4217 format
fee number(float) true none Fee of the transaction
status string true none Status of the transaction
notes string false none Notes of the transaction when load or spend back
payer_name string false none Name of the payer when payout transaction
pickup_code string false none Code/pin that is required when collecting the money when payout transaction
source_token string(uuid) false none Token that represents the funding source i.e. bank account, wallet. 36 characters long
destination_token string(uuid) true none 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
delivery_type string false none The type of service. I.e. cash pickup, home delivery, etc. Only provided for payouts

Enumerated Values

Property Value
type load
type payout
type spend back
type info
status PENDING
status PROCESSING
status COMPLETED
status CANCELLED
status READY_FOR_PICKUP
status HOLD
status ERROR
delivery_type CASH_PICKUP
delivery_type BANK_DEPOSIT
delivery_type HOME_DELIVERY
delivery_type MOBILE_WALLET
delivery_type MASSPAY_CARD

SpendBacks

{
  "spendback_token": "spnd_bk_4275f2-bae1-488d-9d6f-20af1cd83574",
  "time_of_spendback": "2019-07-07T23:03:05",
  "client_spendback_id": "aEjn345",
  "source_token": "usr_wlt_ba4275f2-bae1-488d-9d6f-20af1cd83574",
  "wallet_token": "clnt_wlt_ba4275f2-bae1-488d-9d6f-20af1cd83574",
  "amount": 100.5,
  "source_currency_code": "USD",
  "notes": "Commission payment for July"
}

Properties

Name Type Required Restrictions Description
spendback_token string true none Token representing the load token
time_of_spendback string(YYYY-MM-DDThh:mm:ss) true none The timestamp the spend back was created in the system. Using UTC timestamp.ISO 8601
client_spendback_id string true none A client defined spend back identifier. This is the unique ID assigned to the spend back on your system. Max 50 characters.
source_token string(uuid) true none Token that represents the funding source i.e. bank account, wallet. 36 characters long
wallet_token string(uuid) true none Token that represents the wallet that received the funds. 36 characters long
amount number true none The amount to credit the user's wallet in source currency
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
notes string true none A description for the load. Will be visible to the user receiving the load

Exception

{
  "Exception": "string",
  "Errors": [
    "string"
  ]
}

Exception

Properties

Name Type Required Restrictions Description
Exception string true none Type of exception
Errors [string] true none List of errors