Using the API

URL

The API URLs:

Staging	https://staging-paymentapi.masspay.io/v1/
Production	https://paymentapi.masspay.io/v1/

Authentication

Authentication is managed using an API key that is provided to you. Every HTTP call to our API should contain a custom header called apiKey. The value of this header must be the API key.

Currencies and Amounts

To make our platform support all currencies and to prevent rounding errors, amounts are stored as natural numbers, paired with an exponent. This exponent defines at which position the decimal point/comma is placed, counting from the right.

Say we have and amount of 12.34 USD. It will be stored and presented as 1234 with an exponential of 2. Some currencies, like the Japanese Yen, have no exponent. A transaction amount of ¥1,000 JPY is stored as 1000.

Filtering and Searching

Filters can be used to interact with any object. Objects can be queried by appending parameters to the query string of the URL.

So to get a list of all settled US dollar transactions with an amount equal or greater than 75.00, we would use the following URL:

/v1/transaction?status=SETTLEMENT_COMPLETED&amount>=7500

It's also possible to filter multiple statuses at the same time. For example to retrieve all successful transactions:

/v1/transaction?status[]=SETTLEMENT_COMPLETED&status[]=SETTLEMENT_REQUESTED

Sorting

For list endpoints, you can specify the sort order using the query parameters _sort and _sort-.

Sort order ASC

• Numerical from lowest first
• Text in alphabetical order
• Dates from earliest first

Query parameter: _sort=

/v1/transaction?_sort=created_at

Sort order DESC

• Numerical from highest first
• Text in reverse alphabetical order
• Dates from latest first

Query parameter: _sort-=

/v1/transaction?_sort-=created_at

Populating Results

The API supports population. This means that fields that reference a certain object will be automatically resolved. Population can be achieved by providing the relevant fields the query parameter _populate.

As an example, let's take a payment profile object:

{
    "id": "7c23a50d-8699-431c-a82b-a78718d2b6f6",
    "organisation": "c96b2d81-51db-4a8a-a0e9-19918c168a3c",
    "name": "My profile",
    "currency_code": "USD",
    ...
}

To know the name of the organisation that this payment profile belongs to, we would have to make an api-call requesting the organisation with ID c96b2d81-51db-4a8a-a0e9-19918c168a3c.

Population allows us to let the server do this for us. If we call /paymentprofile/7c23a50d-8699-431c-a82b-a78718d2b6f6?_populate=organisation, we get the following results:

{
    "id": "7c23a50d-8699-431c-a82b-a78718d2b6f6",
    "organisation": {
        "id": "c96b2d81-51db-4a8a-a0e9-19918c168a3c",
        "name": "Example Company",
        "parent_id": "cc5a8e9b-a39a-4e53-b404-668a5426cca2"
    }
    "name": "My profile",
    "currency_code": "USD",
    ...
}

Like with filters it's also possible to populate multiple objects. As an example:

/v1/paymentprofile?_populate[]=organisation&_populate[]=bank_account

Timeout

For any non-GET operation, your system must wait at least 35 seconds for a reply before closing the connection.