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.

Account Holders

Account Holders

Create account holder

This endpoint is used to create an account holder

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

billing
object

Billing

document_id
string

ID of the document

Responses

200

OK

post /account_holders/create
https://api.payall.com/v1/account_holders/create
https://api.sandbox.payall.com/v1/account_holders/create

Request samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "country_code": "string",
  • "legal_entity_type": "INDIVIDUAL",
  • "first_name": "string",
  • "last_name": "string",
  • "birth_date": "2020-01-30",
  • "phone": "string",
  • "email": "string",
  • "billing":
    {
    },
  • "document_id": "string"
}

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "id": "string",
  • "country_code": "string",
  • "legal_entity_type": "INDIVIDUAL",
  • "first_name": "string",
  • "last_name": "string",
  • "birth_date": "2020-01-30",
  • "phone": "string",
  • "email": "string",
  • "billing":
    {
    },
  • "document_id": "string"
}

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

200

OK

post /account_holders/get
https://api.payall.com/v1/account_holders/get
https://api.sandbox.payall.com/v1/account_holders/get

Request samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "id": "string"
}

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "id": "string",
  • "country_code": "string",
  • "legal_entity_type": "INDIVIDUAL",
  • "first_name": "string",
  • "last_name": "string",
  • "birth_date": "2020-01-30",
  • "phone": "string",
  • "email": "string",
  • "billing":
    {
    },
  • "document_id": "string"
}

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

billing
object

Billing

document_id
string

ID of the document

Responses

200

OK

post /account_holders/update
https://api.payall.com/v1/account_holders/update
https://api.sandbox.payall.com/v1/account_holders/update

Request samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "id": "string",
  • "first_name": "string",
  • "last_name": "string",
  • "birth_date": "2020-01-30",
  • "phone": "string",
  • "email": "string",
  • "billing":
    {
    },
  • "document_id": "string"
}

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "id": "string",
  • "country_code": "string",
  • "legal_entity_type": "INDIVIDUAL",
  • "first_name": "string",
  • "last_name": "string",
  • "birth_date": "2020-01-30",
  • "phone": "string",
  • "email": "string",
  • "billing":
    {
    },
  • "document_id": "string"
}

Accounts

Accounts

Create account

This endpoint is used to create an account

Request Body schema: application/json
program_id
string

ID of the program

account_holder
required
object

Account holder

currency_code
required
string
Value:"USD"

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

Responses

200

OK

post /accounts/create
https://api.payall.com/v1/accounts/create
https://api.sandbox.payall.com/v1/accounts/create

Request samples

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

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "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

200

OK

post /accounts/get
https://api.payall.com/v1/accounts/get
https://api.sandbox.payall.com/v1/accounts/get

Request samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "id": "string"
}

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "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

design_id
string

ID of the design

type
required
string
Enum:"VIRTUAL" "PHYSICAL"
cardholder
required
object

Cardholder details

shipping
object

Required when type is PHYSICAL

reference
string <= 100 characters

Reference number associated with this card

amount
string

Load amount

currency_code
string
Value:"USD"

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

Responses

200

OK

post /cards/create
https://api.payall.com/v1/cards/create
https://api.sandbox.payall.com/v1/cards/create

Request samples

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

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "id": "string",
  • "program_id": "string",
  • "design_id": "string",
  • "type": "VIRTUAL",
  • "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

200

OK

post /cards/get
https://api.payall.com/v1/cards/get
https://api.sandbox.payall.com/v1/cards/get

Request samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "id": "string"
}

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "id": "string",
  • "program_id": "string",
  • "design_id": "string",
  • "type": "VIRTUAL",
  • "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
Value:"USD"

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

Responses

200

OK

post /cards/load
https://api.payall.com/v1/cards/load
https://api.sandbox.payall.com/v1/cards/load

Request samples

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

Response samples

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

Payment Instruments

Payment Instruments

Create payment instrument

This endpoint is used to create payment instrument.

Request Body schema: application/json
type
required
string
Value:"CARD"
holder_name
string

Cardholder's full name.

number
string

Card number

expiration
object
security_code
string

Card security code, cvc, cvv

billing
object

Billing information

Responses

200

OK

post /payment_instruments/create
https://api.payall.com/v1/payment_instruments/create
https://api.sandbox.payall.com/v1/payment_instruments/create

Request samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "type": "CARD",
  • "holder_name": "string",
  • "number": "string",
  • "expiration":
    {
    },
  • "security_code": "string",
  • "billing":
    {
    }
}

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "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

200

OK

post /payment_instruments/get
https://api.payall.com/v1/payment_instruments/get
https://api.sandbox.payall.com/v1/payment_instruments/get

Request samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "id": "string"
}

Response samples

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

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
type
required
string
Enum:"TRANSFER" "SALE" "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
Value:"USD"

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

200

OK

post /transactions/create
https://api.payall.com/v1/transactions/create
https://api.sandbox.payall.com/v1/transactions/create

Request samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "type": "TRANSFER",
  • "source": "string",
  • "source_security_code": "string",
  • "destination": "string",
  • "amount": "12.00",
  • "currency_code": "USD",
  • "metadata": { }
}

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "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

200

OK

post /transactions/complete
https://api.payall.com/v1/transactions/complete
https://api.sandbox.payall.com/v1/transactions/complete

Request samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "id": "string",
  • "amount": "12.00"
}

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "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

200

OK

post /transactions/get
https://api.payall.com/v1/transactions/get
https://api.sandbox.payall.com/v1/transactions/get

Request samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "id": "string"
}

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "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

created_at
object

Responses

200

OK

post /transactions/list
https://api.payall.com/v1/transactions/list
https://api.sandbox.payall.com/v1/transactions/list

Request samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "cursor": "string",
  • "limit": "string",
  • "created_at":
    {
    }
}

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "data":
    [
    ],
  • "pagination":
    {
    }
}

Files

Payall's Files functionality allows you to manage files.

Upload file

This endpoint is used to upload file.

Request Body schema: multipart/form-data
file
string <binary>

Responses

200

OK

post /files/upload
https://api.payall.com/v1/files/upload
https://api.sandbox.payall.com/v1/files/upload

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "id": "string",
  • "created_at": "string"
}