The Payall APIs are designed to enable clients to make and receive payments globally by quickly and easily integrating into their native systems without knowing how arcane payment systems work globally or even having many details about the recipient. We’ve integrated a combination of more common methods, new services as well novel techniques pioneered by the company representing the most diverse and ever expanding final-mile payment options possible. This enables the client to make an instant payment to anyone, anywhere and enables the recipient to decide the best way to access their money. (The above is subject to sanctions and regulated entity approvals).
To make API calls, include the bearer token in the Authorization header with the Bearer authentication scheme.
The value is Bearer <Your-Secret-Key>
.
The URL to the API service is either:
Sandbox. https://api.sandbox.payall.com
Live. https://api.payall.com
APIs use the Status-Line part of an HTTP response message to inform clients of their request’s overarching result.
HTTP defines over 40 standard status codes that can be used to convey the results of a client’s request. The status codes are divided into the five categories presented here:
Error Code | Error Description |
---|---|
UNAUTHORIZED | Missing or invalid API Key provided. |
REQUEST_INVALID | The request provided is invalid. Please check details field for more details. |
BALANCE_INSUFFICIENT | The operation could not be completed because the associated account does not have a sufficient balance available. |
This endpoint is used to retrieve a country specifications based on country code
program_id required | string ID of the program provided by Payall |
country_code required | string Two-letter country code (ISO 3166-1 alpha-2) |
{- "program_id": "string",
- "country_code": "string"
}
{- "data": {
- "program_id": "string",
- "country_code": "string",
- "verification_fields": { }
}
}
This endpoint is used to create an account holder
program_id required | string ID of the program provided by Payall |
country_code required | string The country in which the account holder resides. Two-letter country code (ISO 3166-1 alpha-2) |
legal_entity_type required | string Value: "INDIVIDUAL" |
first_name required | string [ 1 .. 50 ] characters |
last_name required | string [ 1 .. 50 ] characters |
birth_date | string <date> Date of birth, in RFC-3339 format |
phone | string The phone number, in E.123 format |
string The email address | |
nationality | string The nationality |
object Billing | |
occupation | Array of strings List of occupation |
source_of_funds | Array of strings List of source of funds |
object National identity | |
object List of documents | |
object Asset wallet | |
object Terms of service acceptance |
{- "program_id": "string",
- "country_code": "string",
- "legal_entity_type": "INDIVIDUAL",
- "first_name": "string",
- "last_name": "string",
- "birth_date": "2019-08-24",
- "phone": "string",
- "email": "string",
- "nationality": "string",
- "billing": {
- "address": {
- "country_code": "string",
- "country_subdivision_code": "string",
- "city": "string",
- "postal_code": "string",
- "line1": "string",
- "line2": "string",
- "county": "string",
- "street_name": "string",
- "street_type": "string",
- "building_name": "string",
- "building_number": "string",
- "unit_number": "string"
}
}, - "occupation": [
- "string"
], - "source_of_funds": [
- "string"
], - "national_identity": {
- "number": "string"
}, - "documents": {
- "proof_of_identity": {
- "type": "string",
- "front_side": "string",
- "back_side": "string",
- "live_photo": "string"
}, - "proof_of_address": {
- "type": "string",
- "front_side": "string",
- "back_side": "string",
- "live_photo": "string"
}, - "additional_proof_of_address": {
- "type": "string",
- "front_side": "string",
- "back_side": "string",
- "live_photo": "string"
}, - "source_of_funds": {
- "type": "string",
- "front_side": "string",
- "back_side": "string",
- "live_photo": "string"
}
}, - "asset_wallet": {
- "address": "string"
}, - "tos_acceptance": {
- "ip": "string",
- "accepted_at": "string"
}
}
{- "id": "string",
- "country_code": "string",
- "legal_entity_type": "INDIVIDUAL",
- "first_name": "string",
- "last_name": "string",
- "birth_date": "2019-08-24",
- "phone": "string",
- "email": "string",
- "billing": {
- "address": {
- "country_code": "string",
- "country_subdivision_code": "string",
- "city": "string",
- "postal_code": "string",
- "line1": "string",
- "line2": "string",
- "county": "string",
- "street_name": "string",
- "street_type": "string",
- "building_name": "string",
- "building_number": "string",
- "unit_number": "string"
}
}, - "occupation": [
- "string"
], - "source_of_funds": [
- "string"
], - "national_identity": {
- "number": "string"
}, - "documents": {
- "proof_of_identity": {
- "type": "string",
- "front_side": "string",
- "back_side": "string",
- "live_photo": "string"
}, - "proof_of_address": {
- "type": "string",
- "front_side": "string",
- "back_side": "string",
- "live_photo": "string"
}, - "additional_proof_of_address": {
- "type": "string",
- "front_side": "string",
- "back_side": "string",
- "live_photo": "string"
}, - "source_of_funds": {
- "type": "string",
- "front_side": "string",
- "back_side": "string",
- "live_photo": "string"
}
}, - "asset_wallet": {
- "address": "string"
}, - "tos_acceptance": {
- "ip": "string",
- "accepted_at": "string"
}, - "verification": {
- "status": "AWAITING_DATA"
}
}
This endpoint is used to retrieve an account holder
id required | string ID of the object |
{- "id": "string"
}
{- "id": "string",
- "country_code": "string",
- "legal_entity_type": "INDIVIDUAL",
- "first_name": "string",
- "last_name": "string",
- "birth_date": "2019-08-24",
- "phone": "string",
- "email": "string",
- "billing": {
- "address": {
- "country_code": "string",
- "country_subdivision_code": "string",
- "city": "string",
- "postal_code": "string",
- "line1": "string",
- "line2": "string",
- "county": "string",
- "street_name": "string",
- "street_type": "string",
- "building_name": "string",
- "building_number": "string",
- "unit_number": "string"
}
}, - "occupation": [
- "string"
], - "source_of_funds": [
- "string"
], - "national_identity": {
- "number": "string"
}, - "documents": {
- "proof_of_identity": {
- "type": "string",
- "front_side": "string",
- "back_side": "string",
- "live_photo": "string"
}, - "proof_of_address": {
- "type": "string",
- "front_side": "string",
- "back_side": "string",
- "live_photo": "string"
}, - "additional_proof_of_address": {
- "type": "string",
- "front_side": "string",
- "back_side": "string",
- "live_photo": "string"
}, - "source_of_funds": {
- "type": "string",
- "front_side": "string",
- "back_side": "string",
- "live_photo": "string"
}
}, - "asset_wallet": {
- "address": "string"
}, - "tos_acceptance": {
- "ip": "string",
- "accepted_at": "string"
}, - "verification": {
- "status": "AWAITING_DATA"
}
}
This endpoint is used to update an account holder
id required | string |
first_name required | string [ 1 .. 50 ] characters |
last_name required | string [ 1 .. 50 ] characters |
birth_date | string <date> Date of birth, in RFC-3339 format |
phone | string The phone number, in E.123 format |
string The email address | |
object Billing | |
occupation | Array of strings List of occupation |
source_of_funds | Array of strings List of occupation |
object National ID | |
object List of documents | |
object Asset wallet | |
object Terms of service acceptance |
{- "id": "string",
- "first_name": "string",
- "last_name": "string",
- "birth_date": "2019-08-24",
- "phone": "string",
- "email": "string",
- "billing": {
- "address": {
- "country_code": "string",
- "country_subdivision_code": "string",
- "city": "string",
- "postal_code": "string",
- "line1": "string",
- "line2": "string",
- "county": "string",
- "street_name": "string",
- "street_type": "string",
- "building_name": "string",
- "building_number": "string",
- "unit_number": "string"
}
}, - "occupation": [
- "string"
], - "source_of_funds": [
- "string"
], - "national_identity": {
- "number": "string"
}, - "documents": {
- "proof_of_identity": {
- "type": "string",
- "front_side": "string",
- "back_side": "string",
- "live_photo": "string"
}, - "proof_of_address": {
- "type": "string",
- "front_side": "string",
- "back_side": "string",
- "live_photo": "string"
}, - "additional_proof_of_address": {
- "type": "string",
- "front_side": "string",
- "back_side": "string",
- "live_photo": "string"
}, - "source_of_funds": {
- "type": "string",
- "front_side": "string",
- "back_side": "string",
- "live_photo": "string"
}
}, - "asset_wallet": {
- "address": "string"
}, - "tos_acceptance": {
- "ip": "string",
- "accepted_at": "string"
}
}
{- "id": "string",
- "country_code": "string",
- "legal_entity_type": "INDIVIDUAL",
- "first_name": "string",
- "last_name": "string",
- "birth_date": "2019-08-24",
- "phone": "string",
- "email": "string",
- "billing": {
- "address": {
- "country_code": "string",
- "country_subdivision_code": "string",
- "city": "string",
- "postal_code": "string",
- "line1": "string",
- "line2": "string",
- "county": "string",
- "street_name": "string",
- "street_type": "string",
- "building_name": "string",
- "building_number": "string",
- "unit_number": "string"
}
}, - "occupation": [
- "string"
], - "source_of_funds": [
- "string"
], - "national_identity": {
- "number": "string"
}, - "documents": {
- "proof_of_identity": {
- "type": "string",
- "front_side": "string",
- "back_side": "string",
- "live_photo": "string"
}, - "proof_of_address": {
- "type": "string",
- "front_side": "string",
- "back_side": "string",
- "live_photo": "string"
}, - "additional_proof_of_address": {
- "type": "string",
- "front_side": "string",
- "back_side": "string",
- "live_photo": "string"
}, - "source_of_funds": {
- "type": "string",
- "front_side": "string",
- "back_side": "string",
- "live_photo": "string"
}
}, - "asset_wallet": {
- "address": "string"
}, - "tos_acceptance": {
- "ip": "string",
- "accepted_at": "string"
}, - "verification": {
- "status": "AWAITING_DATA"
}
}
This endpoint is used to create an account
program_id | string ID of the program provided by Payall |
required | object Account holder |
currency_code required |
{- "program_id": "string",
- "account_holder": {
- "program_id": "string",
- "country_code": "string",
- "legal_entity_type": "INDIVIDUAL",
- "first_name": "string",
- "last_name": "string",
- "birth_date": "2019-08-24",
- "phone": "string",
- "email": "string",
- "nationality": "string",
- "billing": {
- "address": {
- "country_code": "string",
- "country_subdivision_code": "string",
- "city": "string",
- "postal_code": "string",
- "line1": "string",
- "line2": "string",
- "county": "string",
- "street_name": "string",
- "street_type": "string",
- "building_name": "string",
- "building_number": "string",
- "unit_number": "string"
}
}, - "occupation": [
- "string"
], - "source_of_funds": [
- "string"
], - "national_identity": {
- "number": "string"
}, - "documents": {
- "proof_of_identity": {
- "type": "string",
- "front_side": "string",
- "back_side": "string",
- "live_photo": "string"
}, - "proof_of_address": {
- "type": "string",
- "front_side": "string",
- "back_side": "string",
- "live_photo": "string"
}, - "additional_proof_of_address": {
- "type": "string",
- "front_side": "string",
- "back_side": "string",
- "live_photo": "string"
}, - "source_of_funds": {
- "type": "string",
- "front_side": "string",
- "back_side": "string",
- "live_photo": "string"
}
}, - "asset_wallet": {
- "address": "string"
}, - "tos_acceptance": {
- "ip": "string",
- "accepted_at": "string"
}
}, - "currency_code": "USD"
}
{- "id": "string",
- "program_id": "string",
- "account_holder": "string",
- "balance": {
- "value": "12.00",
- "currency": "USD"
}
}
This endpoint is used to retrieve an account
id required | string ID of the object |
{- "id": "string"
}
{- "id": "string",
- "program_id": "string",
- "account_holder": "string",
- "balance": {
- "value": "12.00",
- "currency": "USD"
}
}
This endpoint is used to create a card and load the card with specified amount
program_id required | string ID of the program provided by Payall |
design_id | string ID of the design |
type required | string Enum: "VIRTUAL" "PHYSICAL" |
account_holder | string ID of the account holder |
object Cardholder details | |
object Required when | |
reference | string <= 100 characters Reference number associated with this card |
amount | string Load amount |
currency_code |
{- "program_id": "string",
- "design_id": "string",
- "type": "VIRTUAL",
- "account_holder": "string",
- "cardholder": {
- "country_code": "string",
- "first_name": "string",
- "last_name": "string",
- "birth_date": "2019-08-24",
- "phone": "string",
- "email": "string",
- "billing": {
- "address": {
- "country_code": "string",
- "country_subdivision_code": "string",
- "city": "string",
- "postal_code": "string",
- "line1": "string",
- "line2": "string",
- "county": "string",
- "street_name": "string",
- "street_type": "string",
- "building_name": "string",
- "building_number": "string",
- "unit_number": "string"
}
}
}, - "shipping": {
- "address": {
- "country_code": "string",
- "country_subdivision_code": "string",
- "city": "string",
- "postal_code": "string",
- "line1": "string",
- "line2": "string"
}
}, - "reference": "string",
- "amount": "12.00",
- "currency_code": "USD"
}
{- "id": "string",
- "program_id": "string",
- "design_id": "string",
- "type": "VIRTUAL",
- "account_holder": "string",
- "cardholder": "string",
- "reference": "string",
- "amount": "12.00",
- "currency_code": "USD"
}
This endpoint is used to retrieve a card
id required | string ID of the object |
{- "id": "string"
}
{- "id": "string",
- "program_id": "string",
- "design_id": "string",
- "type": "VIRTUAL",
- "account_holder": "string",
- "cardholder": "string",
- "reference": "string",
- "amount": "12.00",
- "currency_code": "USD"
}
This endpoint is used to credit value to an assigned card.
account_id required | string ID of the account |
card_id required | string ID of the card |
amount required | string Load amount |
currency_code required |
{- "account_id": "string",
- "card_id": "string",
- "amount": "12.00",
- "currency_code": "USD"
}
{- "id": "string",
- "source": "string",
- "destination": "string",
- "amount": "12.00",
- "currency_code": "USD",
- "status": "string",
- "created_at": "string",
- "metadata": { }
}
This endpoint is used to list cards.
cursor | string A cursor for use in pagination |
limit | string A limit on the number of objects to be returned |
object |
{- "cursor": "string",
- "limit": "string",
- "created_at": {
- "gt": "string",
- "gte": "string",
- "lt": "string",
- "lte": "string"
}
}
{- "data": [
- {
- "id": "string",
- "type": "TRANSFER",
- "source": "string",
- "destination": "string",
- "amount": "12.00",
- "currency_code": "USD",
- "status": "string",
- "created_at": "string",
- "metadata": { }
}
], - "pagination": {
- "has_more": true
}
}
This endpoint is used to change card status.
card_id required | string ID of the card |
status required | string Enum: "INACTIVE" "ACTIVE" |
{- "card_id": "string",
- "status": "INACTIVE"
}
{- "id": "string",
- "program_id": "string",
- "design_id": "string",
- "type": "VIRTUAL",
- "account_holder": "string",
- "cardholder": "string",
- "reference": "string",
- "amount": "12.00",
- "currency_code": "USD"
}
This endpoint is used to list card transactions.
cursor | string A cursor for use in pagination |
limit | string A limit on the number of objects to be returned |
object |
{- "cursor": "string",
- "limit": "string",
- "created_at": {
- "gt": "string",
- "gte": "string",
- "lt": "string",
- "lte": "string"
}
}
{- "data": [
- {
- "id": "string",
- "type": "TRANSFER",
- "source": "string",
- "destination": "string",
- "amount": "12.00",
- "currency_code": "USD",
- "status": "string",
- "created_at": "string",
- "metadata": { }
}
], - "pagination": {
- "has_more": true
}
}
This endpoint is used to create payment instrument.
type required | string Value: "CARD" |
holder_name | string Cardholder's full name. |
number | string Card number |
object | |
security_code | string Card security code, cvc, cvv |
object Billing information |
{- "type": "CARD",
- "holder_name": "string",
- "number": "string",
- "expiration": {
- "month": "string",
- "year": "string"
}, - "security_code": "string",
- "billing": {
- "address": {
- "country_code": "string",
- "country_subdivision_code": "string",
- "city": "string",
- "postal_code": "string",
- "line1": "string",
- "line2": "string",
- "county": "string",
- "street_name": "string",
- "street_type": "string",
- "building_name": "string",
- "building_number": "string",
- "unit_number": "string"
}
}
}
{- "id": "string",
- "type": "CARD",
- "holder_name": "string",
- "number_last4": "string",
- "expiration": {
- "month": "string",
- "year": "string"
}, - "billing": {
- "address": {
- "country_code": "string",
- "country_subdivision_code": "string",
- "city": "string",
- "postal_code": "string",
- "line1": "string",
- "line2": "string",
- "county": "string",
- "street_name": "string",
- "street_type": "string",
- "building_name": "string",
- "building_number": "string",
- "unit_number": "string"
}
}
}
This endpoint is used to retrieve payment instrument.
id required | string ID of the object |
{- "id": "string"
}
{- "id": "string",
- "type": "CARD",
- "holder_name": "string",
- "number_last4": "string",
- "expiration": {
- "month": "string",
- "year": "string"
}, - "billing": {
- "address": {
- "country_code": "string",
- "country_subdivision_code": "string",
- "city": "string",
- "postal_code": "string",
- "line1": "string",
- "line2": "string",
- "county": "string",
- "street_name": "string",
- "street_type": "string",
- "building_name": "string",
- "building_number": "string",
- "unit_number": "string"
}
}
}
This endpoint is used to initiate a payment
program_id required | string ID of the program |
reference | string Reference ID is your organization's unique identifier for this payment |
first_name required | string [ 1 .. 50 ] characters |
last_name required | string [ 1 .. 50 ] characters |
phone required | string The phone number, in E.123 format |
email required | string |
currency_code | |
amount required | string |
message | string |
type required | Array of strings Items Enum: "GFA" "ACH" "SEPA" "SAMEDAYACH" "RTP" "INSTANT_PAYMENT" "VIRTUAL_CARD" "PHYSICAL_CARD" |
{- "program_id": "string",
- "reference": "string",
- "first_name": "string",
- "last_name": "string",
- "phone": "string",
- "email": "string",
- "currency_code": "USD",
- "amount": "12.00",
- "message": "string",
- "type": [
- "GFA"
]
}
{- "program_id": "string",
- "reference": "string",
- "first_name": "string",
- "last_name": "string",
- "phone": "string",
- "email": "string",
- "currency_code": "USD",
- "amount": "12.00",
- "message": "string",
- "type": [
- "GFA"
]
}
This endpoint is used to retrieve exchange rates.
program_id required | string ID of the program provided by Payall |
currency_code required |
{- "program_id": "string",
- "currency_code": "BCH"
}
{- "currency_code": "BCH",
- "rates": [
- {
- "currency_code": "USD",
- "rate": "string"
}
]
}
This endpoint is used to create a transaction.
type required | string Value: "AUTHORIZATION" |
source required | string ID of the source |
source_security_code | string Security code, cvc, cvv |
destination required | string ID of the destination |
amount required | string Load amount |
currency_code required | |
metadata | object A set of key-value pairs that you can attach to a Transaction object. This can be useful for storing additional information about the transaction in a structured format. |
{- "type": "AUTHORIZATION",
- "source": "string",
- "source_security_code": "string",
- "destination": "string",
- "amount": "12.00",
- "currency_code": "USD",
- "metadata": { }
}
{- "id": "string",
- "source": "string",
- "destination": "string",
- "amount": "12.00",
- "currency_code": "USD",
- "status": "string",
- "created_at": "string",
- "metadata": { }
}
This endpoint is used to complete a transaction.
id required | string ID of the transaction |
amount required | string Transaction amount |
{- "id": "string",
- "amount": "12.00"
}
{- "id": "string",
- "source": "string",
- "destination": "string",
- "amount": "12.00",
- "currency_code": "USD",
- "status": "string",
- "created_at": "string",
- "metadata": { }
}
This endpoint is used to retrieve a transaction.
id required | string ID of the object |
{- "id": "string"
}
{- "id": "string",
- "source": "string",
- "destination": "string",
- "amount": "12.00",
- "currency_code": "USD",
- "status": "string",
- "created_at": "string",
- "metadata": { }
}
This endpoint is used to list transactions.
cursor | string A cursor for use in pagination |
limit | string A limit on the number of objects to be returned |
object |
{- "cursor": "string",
- "limit": "string",
- "created_at": {
- "gt": "string",
- "gte": "string",
- "lt": "string",
- "lte": "string"
}
}
{- "data": [
- {
- "id": "string",
- "type": "TRANSFER",
- "source": "string",
- "destination": "string",
- "amount": "12.00",
- "currency_code": "USD",
- "status": "string",
- "created_at": "string",
- "metadata": { }
}
], - "pagination": {
- "has_more": true
}
}
This endpoint is used to upload a file.
program_id required | string ID of the program provided by Payall |
type required | string Enum: "PROOF_OF_IDENTITY" "PROOF_OF_ADDRESS" The type of the uploaded file |
file required | string <binary> A file to upload |
curl -X POST \ https://api.sandbox.payall.com/v1/files/upload \ -H "Content-Type: multipart/form-data" \ -H "Authorization: Bearer <Your-Secret-Key>" -F "program_id=<provided_program_id>", -F "type=PROOF_OF_IDENTITY", -F "file=@path/to/file.jpeg"
{- "data": {
- "id": "string",
- "created_at": "string"
}
}