logo
Documentation Powered by ReDoc

Payall (1.0)

Introduction

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

Authenticate

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:

Errors

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:

  • 1xx: Informational - Communicates transfer protocol-level information
  • 2xx: Success - Indicates that the client’s request was accepted successfully.
  • 3xx: Redirection - Indicates that the client must take some additional action in order to complete their request.
  • 4xx: Client Error - This category of error status codes points the finger at clients.
  • 5xx: Server Error - The server takes responsibility for these error status codes.
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.

Country Specifications

Country Specifications

Retrieve country specifications

This endpoint is used to retrieve a country specifications based on country code

Request Body schema: application/json
program_id
required
string

ID of the program provided by Payall

country_code
required
string

Two-letter country code (ISO 3166-1 alpha-2)

Responses

Request samples

Content type
application/json
{
  • "program_id": "string",
  • "country_code": "string"
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

Account Holders

Account Holders

Create account holder

This endpoint is used to create an account holder

Request Body schema: application/json
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

email
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

Responses

Request samples

Content type
application/json
{
  • "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": {
    },
  • "occupation": [
    ],
  • "source_of_funds": [
    ],
  • "national_identity": {
    },
  • "documents": {
    },
  • "asset_wallet": {
    },
  • "tos_acceptance": {
    }
}

Response samples

Content type
application/json
{
  • "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": {
    },
  • "occupation": [
    ],
  • "source_of_funds": [
    ],
  • "national_identity": {
    },
  • "documents": {
    },
  • "asset_wallet": {
    },
  • "tos_acceptance": {
    },
  • "verification": {
    }
}

Retrieve account holder

This endpoint is used to retrieve an account holder

Request Body schema: application/json
id
required
string

ID of the object

Responses

Request samples

Content type
application/json
{
  • "id": "string"
}

Response samples

Content type
application/json
{
  • "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": {
    },
  • "occupation": [
    ],
  • "source_of_funds": [
    ],
  • "national_identity": {
    },
  • "documents": {
    },
  • "asset_wallet": {
    },
  • "tos_acceptance": {
    },
  • "verification": {
    }
}

Update account holder

This endpoint is used to update an account holder

Request Body schema: application/json
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

email
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

Responses

Request samples

Content type
application/json
{
  • "id": "string",
  • "first_name": "string",
  • "last_name": "string",
  • "birth_date": "2019-08-24",
  • "phone": "string",
  • "email": "string",
  • "billing": {
    },
  • "occupation": [
    ],
  • "source_of_funds": [
    ],
  • "national_identity": {
    },
  • "documents": {
    },
  • "asset_wallet": {
    },
  • "tos_acceptance": {
    }
}

Response samples

Content type
application/json
{
  • "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": {
    },
  • "occupation": [
    ],
  • "source_of_funds": [
    ],
  • "national_identity": {
    },
  • "documents": {
    },
  • "asset_wallet": {
    },
  • "tos_acceptance": {
    },
  • "verification": {
    }
}

Accounts

Accounts

Create account

This endpoint is used to create an account

Request Body schema: application/json
program_id
string

ID of the program provided by Payall

required
object

Account holder

currency_code
required
string
Enum: "USD" "EUR"

The three-character ISO-4217 currency code that identifies the currency.

Responses

Request samples

Content type
application/json
{
  • "program_id": "string",
  • "account_holder": {
    },
  • "currency_code": "USD"
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "program_id": "string",
  • "account_holder": "string",
  • "balance": {
    }
}

Retrieve account

This endpoint is used to retrieve an account

Request Body schema: application/json
id
required
string

ID of the object

Responses

Request samples

Content type
application/json
{
  • "id": "string"
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "program_id": "string",
  • "account_holder": "string",
  • "balance": {
    }
}

Cards

Payall's Cards functionality allows you to create, activate, assign and load cards.

Create card

This endpoint is used to create a card and load the card with specified amount

Request Body schema: application/json
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 type is PHYSICAL

reference
string <= 100 characters

Reference number associated with this card

amount
string

Load amount

currency_code
string
Enum: "USD" "EUR"

The three-character ISO-4217 currency code that identifies the currency.

Responses

Request samples

Content type
application/json
{
  • "program_id": "string",
  • "design_id": "string",
  • "type": "VIRTUAL",
  • "account_holder": "string",
  • "cardholder": {
    },
  • "shipping": {
    },
  • "reference": "string",
  • "amount": "12.00",
  • "currency_code": "USD"
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "program_id": "string",
  • "design_id": "string",
  • "type": "VIRTUAL",
  • "account_holder": "string",
  • "cardholder": "string",
  • "reference": "string",
  • "amount": "12.00",
  • "currency_code": "USD"
}

Retrieve card

This endpoint is used to retrieve a card

Request Body schema: application/json
id
required
string

ID of the object

Responses

Request samples

Content type
application/json
{
  • "id": "string"
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "program_id": "string",
  • "design_id": "string",
  • "type": "VIRTUAL",
  • "account_holder": "string",
  • "cardholder": "string",
  • "reference": "string",
  • "amount": "12.00",
  • "currency_code": "USD"
}

Load card

This endpoint is used to credit value to an assigned card.

Request Body schema: application/json
account_id
required
string

ID of the account

card_id
required
string

ID of the card

amount
required
string

Load amount

currency_code
required
string
Enum: "USD" "EUR"

The three-character ISO-4217 currency code that identifies the currency.

Responses

Request samples

Content type
application/json
{
  • "account_id": "string",
  • "card_id": "string",
  • "amount": "12.00",
  • "currency_code": "USD"
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "source": "string",
  • "destination": "string",
  • "amount": "12.00",
  • "currency_code": "USD",
  • "status": "string",
  • "created_at": "string",
  • "metadata": { }
}

List cards

This endpoint is used to list cards.

Request Body schema: application/json
cursor
string

A cursor for use in pagination

limit
string

A limit on the number of objects to be returned

object

Responses

Request samples

Content type
application/json
{
  • "cursor": "string",
  • "limit": "string",
  • "created_at": {
    }
}

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "pagination": {
    }
}

Change card status

This endpoint is used to change card status.

Request Body schema: application/json
card_id
required
string

ID of the card

status
required
string
Enum: "INACTIVE" "ACTIVE"

Responses

Request samples

Content type
application/json
{
  • "card_id": "string",
  • "status": "INACTIVE"
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "program_id": "string",
  • "design_id": "string",
  • "type": "VIRTUAL",
  • "account_holder": "string",
  • "cardholder": "string",
  • "reference": "string",
  • "amount": "12.00",
  • "currency_code": "USD"
}

List card transactions

This endpoint is used to list card transactions.

Request Body schema: application/json
cursor
string

A cursor for use in pagination

limit
string

A limit on the number of objects to be returned

object

Responses

Request samples

Content type
application/json
{
  • "cursor": "string",
  • "limit": "string",
  • "created_at": {
    }
}

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "pagination": {
    }
}

Payment Instruments

Payment Instruments

Create payment instrument

This endpoint is used to create payment instrument.

Request Body schema: application/json
One of
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

Responses

Request samples

Content type
application/json
Example
CardPaymentInstrument
CardPaymentInstrument
BankAccountPaymentInstrument
{
  • "type": "CARD",
  • "holder_name": "string",
  • "number": "string",
  • "expiration": {
    },
  • "security_code": "string",
  • "billing": {
    }
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "type": "CARD",
  • "holder_name": "string",
  • "number_last4": "string",
  • "expiration": {
    },
  • "billing": {
    }
}

Retrieve payment instrument

This endpoint is used to retrieve payment instrument.

Request Body schema: application/json
id
required
string

ID of the object

Responses

Request samples

Content type
application/json
{
  • "id": "string"
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "type": "CARD",
  • "holder_name": "string",
  • "number_last4": "string",
  • "expiration": {
    },
  • "billing": {
    }
}

Payments

Payall's Payments functionality allows you to manage payments.

Initiate payment

This endpoint is used to initiate a payment

Request Body schema: application/json
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
string
Enum: "USD" "EUR"

The three-character ISO-4217 currency code that identifies the currency.

amount
required
string
message
string
type
required
Array of strings
Items Enum: "GFA" "ACH" "SEPA" "SAMEDAYACH" "RTP" "INSTANT_PAYMENT" "VIRTUAL_CARD" "PHYSICAL_CARD"

Responses

Request samples

Content type
application/json
{
  • "program_id": "string",
  • "reference": "string",
  • "first_name": "string",
  • "last_name": "string",
  • "phone": "string",
  • "email": "string",
  • "currency_code": "USD",
  • "amount": "12.00",
  • "message": "string",
  • "type": [
    ]
}

Response samples

Content type
application/json
{
  • "program_id": "string",
  • "reference": "string",
  • "first_name": "string",
  • "last_name": "string",
  • "phone": "string",
  • "email": "string",
  • "currency_code": "USD",
  • "amount": "12.00",
  • "message": "string",
  • "type": [
    ]
}

Exchange Rates

Exchange Rates.

Retrieve exchange rates

This endpoint is used to retrieve exchange rates.

Request Body schema: application/json
program_id
required
string

ID of the program provided by Payall

currency_code
required
string
Enum: "BCH" "BTC"

The three-character ISO-4217 currency code that identifies the currency.

Responses

Request samples

Content type
application/json
{
  • "program_id": "string",
  • "currency_code": "BCH"
}

Response samples

Content type
application/json
{
  • "currency_code": "BCH",
  • "rates": [
    ]
}

Transactions

Payall's Transactions functionality allows you to manage transactions.

Create transaction

This endpoint is used to create a transaction.

Request Body schema: application/json
One of
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
string
Enum: "USD" "EUR"

The three-character ISO-4217 currency code that identifies the currency.

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.

Responses

Request samples

Content type
application/json
Example
AuthorizationTransaction
AuthorizationTransaction
SaleTransaction
AssetSaleTransaction
ACHTransaction
SameDayACHTransaction
RTPTransaction
SEPATransaction
InstantPaymentTransaction
{
  • "type": "AUTHORIZATION",
  • "source": "string",
  • "source_security_code": "string",
  • "destination": "string",
  • "amount": "12.00",
  • "currency_code": "USD",
  • "metadata": { }
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "source": "string",
  • "destination": "string",
  • "amount": "12.00",
  • "currency_code": "USD",
  • "status": "string",
  • "created_at": "string",
  • "metadata": { }
}

Complete transaction

This endpoint is used to complete a transaction.

Request Body schema: application/json
id
required
string

ID of the transaction

amount
required
string

Transaction amount

Responses

Request samples

Content type
application/json
{
  • "id": "string",
  • "amount": "12.00"
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "source": "string",
  • "destination": "string",
  • "amount": "12.00",
  • "currency_code": "USD",
  • "status": "string",
  • "created_at": "string",
  • "metadata": { }
}

Retrieve transaction

This endpoint is used to retrieve a transaction.

Request Body schema: application/json
id
required
string

ID of the object

Responses

Request samples

Content type
application/json
{
  • "id": "string"
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "source": "string",
  • "destination": "string",
  • "amount": "12.00",
  • "currency_code": "USD",
  • "status": "string",
  • "created_at": "string",
  • "metadata": { }
}

List transactions

This endpoint is used to list transactions.

Request Body schema: application/json
cursor
string

A cursor for use in pagination

limit
string

A limit on the number of objects to be returned

object

Responses

Request samples

Content type
application/json
{
  • "cursor": "string",
  • "limit": "string",
  • "created_at": {
    }
}

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "pagination": {
    }
}

Files

Payall's Files functionality allows you to manage files.

Upload file

This endpoint is used to upload a file.

Request Body schema: multipart/form-data
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

Responses

Request samples 

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"

Response samples

Content type
application/json
{
  • "data": {
    }
}