Data Types

In this section we describe the data types and formats generally used by the Send Payments API.

JSON data types

Generally, when the Send Payments API requires a body parameter within a request or when it returns a body parameter in a response or Webhook outbound request, then the body is a JSON object.

For requests (to Send, and from Send Webhooks to your Endpoints), when the Content-Type parameter is set to application/json and for responses to GET requests, the body parameter conforms to ECMA standard JSON which is limited to the JSON data types:

• string
• number
• JSON object
• array
• true
• false

Underlying data types

In addition to the JSON data types, we provide the underlying data types that are contained within the JSON data type, and formats for each JSON object. In some cases, these aren’t data types in the strict sense but are descriptions of common formats.
e.g. we describe our unique identifiers as UUID.

Where we have included a defined data type, e.g. String, then we have included the language (usually JavaScript) so you know the correct definition.

Where the specific key value has a length or format requirement that is different from the basic data types below, then we will provide this in the endpoint description.

Although not strictly enforced, the table below is a guide to the minimum and maximum sizes and formats that the data within the body parameter of a request or response is likely to take.

e.g. The JSON key named birthDate is a string, but it has a generic underlying data type representing a date and is in the format “YYYY-MM-DD”.

"birthDate" : "1984-08-04"

Amount key value pairs

Denoting amounts in international currencies can be tricky because many have varying denominations f.e cents and dollars, or pennies and pounds. To ensure consistency throughout the API, amounts are always defined by a currencies lowest value denomination as a 64 bit integer.

Floating point data types are not used for amounts as some mathematical operations on floats can result in a loss of accuracy.

Note: floating point numbers are used for some key values such as rates, but not for currency amounts.
For dollar currencies (like $AUD), $110 and $0.15 would be represented as follows:

"amount": 11000,
"amount": 15

Some currencies (Like ¥JPY) have only one denomination. ¥110 would be represented as follows:

"amount": 110

Enumerations (Enums)

Some JSON objects must take one of a specific set of values exactly. We will tell you when a key value is an Enum so you'll know which values must be used. e.g. The JSON object named “identityType” is a JSON string, but it has an underlying data type which must be a value from a specific set of values i.e. it is an enumerated type or Enum.

Enum name: “EnumIdentityType”

Enum allowed values: “drivers_license”, “passport”

You might use it like this:

{"identityType" : "drivers_license"}
or
{"identityType" : "passport"}

but any other value would cause and error (not the space character)
{"identityType" : "drivers license"}

Lists

In the Send Payments API documentation, Lists are reference data, similar to Enums. When we talk about Lists we mean it in the way you would use it in everyday English, we do not mean an ordered list of values as in the computer science definition. Some JSON objects must take one of a specific list of values exactly. We will tell you when a key value must be from a List.

Send Payments API Lists require key values to come from a specified list of values, however they differ from Enums in that they:

• Are more likely to change over time.

  • new values added, existing values removed.
  • values activated or deactivated temporarily.
  • e.g. Send Payments does not offer payments in certain currencies, however, Send Payments may at its discretion, enable or disable a currency in the future.

• May be limited by agreement with a customer. The details of your agreement with Send Payments may mean that certain options are unavailable or are irrelevant to you.

  • e.g. You may require access to certain currencies but not others.

• Changes do not necessarily require a new version of the API.

Agreement level lists are shared with your organization as part of your agreement with Send Payments.

📘

Not Seeing What You're Looking For?

We are always looking to improve our API documentation to ensure Sends systems are easy to understand and quick to build against. If you're struggling to find the answer to a question we either haven't made it easy enough to find the relevant docs or we haven't had a chance to write something up for it yet.

Either way we want to hear from you!

Head over to our Discussion Board and leave us a note. We keep a close eye on this and want to ensure we make these docs as useful as they can be so will jump on any posts quickly.