API docs by Redocly

Payall M2M Authentication API (2.0)

Download OpenAPI specification:

URL: https://payall.com

This is Payall's public API for Machine to Machine communication.

Authorization

Get an access token

This endpoint is used to get an access token.

Authorizations:
basicAuth

Responses

Response samples

Content type
application/json
{
  • "access_token": "string",
  • "token_type": "Bearer",
  • "expires_in": 300
}

Discovery

Get required payment fields

Provides information about the fields required to make a payment based on supplied parameters. Different payment channels will yield various results based on payment processors and compliance requirements.

Data provided by this endpoint can be used to build UI for customers to provide relevant payment data or to just collect it from internal system to execute the payment swiftly by avoiding holdups due to missing data.

Please note that response from this endpoint will not include base fields required by Recipient entities (like first or last name of a person).

Sample response for B2P payment of 100 PLN to Poland from EUR account:

{
    "dob": {
      "title": "Date of birth",
      "data_type": "DOB",
    },
    "registration_address": {
      "city": {
        "mask": "^[a-zA-Z\/\\\\-:().,='+0-9\\\\s]{1,35}$",
        "title": "City",
        "data_type": "STRING",
        "max_length": 255,
        "min_length": 1,
      },
      "street": {
        "mask": "^[a-zA-Z\/\\-:().,='+0-9\\s]{1,35}$",
        "title": "Street name",
        "data_type": "STRING",
        "max_length": 255,
        "min_length": 1,
      },
      "country": {
        "title": "Country of residence",
        "data_type": "COUNTRY",
      }
    }
}

Sample response for B2B payment of 100 PLN to Poland from EUR account:

{
    "registration_address": {
      "city": {
        "mask": "^[a-zA-Z\/\\\\-:().,='+0-9\\\\s]{1,35}$",
        "title": "City",
        "data_type": "STRING",
        "max_length": 255,
        "min_length": 1,
      },
      "street": {
        "mask": "^[a-zA-Z\/\\-:().,='+0-9\\s]{1,35}$",
        "title": "Street name",
        "data_type": "STRING",
        "max_length": 255,
        "min_length": 1,
      },
      "country": {
        "title": "Country of residence",
        "data_type": "COUNTRY",
      }
    }
}
Authorizations:
OAuth2
query Parameters
recipient_country
required
string <iso-3166-alpha-2>
Example: recipient_country=IT
payment_type
required
string
Enum: "B2P" "B2B" "P2B" "P2P"
payer_currency
required
string <iso-4217> = 3 characters
Example: payer_currency=USD
instrument_category
required
string
Enum: "BankAccount" "MobileWallet" "CashPickup" "Card"
amount
required
integer
Example: amount=100023

Amounts are always in the smallest currency unit. Example: 1000.23 USD is represented as 100023 cents.

recipient_currency
required
string <iso-4217> = 3 characters
Example: recipient_currency=EUR

Responses

Response samples

Content type
application/json
{
  • "recipient": {
    },
  • "payment_instrument": {
    },
  • "kyt": {
    },
  • "example": {
    }
}

Payments

Initiate a single payment

Use this method to initiate a single Payment.

Authorizations:
OAuth2
Request Body schema: application/json
required
One of
end_to_end_id
string (EndToEndId) <= 35 characters

End To End Identification This filed follows ISO 20022 guidelines.

Unique identification, as assigned by the initiating party, to unambiguously identify the transaction. This identification is passed on, unchanged, throughout the entire end-to-end chain.

Usage: The end-to-end identification can be used for reconciliation or to link tasks relating to the transaction. It can be included in several messages related to the transaction.

If not provided, a random UUID based identifier will be generated.

client_payment_id
string

External reference identifying the payment in your (the client) system.

Person (object) or Business (object)

[Optional] New recipient information.

This recipient will be persisted for the future and linked to the payment instrument provided via the payment_instrument field. When creating new recipient you can not reuse existing payment instrument as it will be already tied to other existing recipient.

If recipient data matches existing recipient in the system then existing recipient will be used and it's ID will be returned in the corresponding PaymentResponse.

Matching is done based on the required fields for Person or Business respectively.

Alternatively recipient_id can be used instead to send payment to existing recipient. recipient and recipient_id are mutually exclusive fields.

MobileWallet (object) or BankAccount (object) or CashPickup (object) or Card (object)

[Optional] New payment instrument information. This payment instrument will be persisted and linked to the recipient provided via the recipient or recipient_id fields.

Alternatively payment_instrument_id can be used instead to reuse existing payment instrument.

recipient_id
string <uuid>

[Optional] Id of exiting recipient.

Alternatively recipient can be used instead to send payment to a new recipient. recipient and recipient_id are mutually exclusive fields.

payment_instrument_id
string <uuid>

[Optional] Id of existing payment instrument.

When payment_instrument_id is provided then recipient_id, recipient and payment_instrument are not allowed because existing instances of PaymentInstrument are tied to specific existing recipients.

source_account_id
required
string <uuid>

Id of the account to use as source of funds.

ForwardPaymentOperation (object) or ReversePaymentOperation (object)
exchange_rate_id
string <uuid>

[Optional] Id of the exchange rate to use for the payment. If not provided then the best available exchange rate will be used.

Note that this is the ID of the exchange rate obtained from the /v2/exchange-rates endpoint. For carded rates use the carded_rate_id.

You can either use the exchange_rate_id or carded_rate_id but not both.

Response with HTTP code 400 will be sent if provided exchange rate expired.

carded_rate_id
string <uuid>

[Optional] Id of the carded exchange rate to use for the payment. If not provided then the best available carded exchange rate will be used.

Note that this is the ID of the exchange rate obtained from the carded rates feed. For non-carded rates use the exchange_rate_id.

You can either use the exchange_rate_id or carded_rate_id but not both.

Response with HTTP code 400 will be sent if provided exchange rate expired.

required
object (KYT)

Transaction information required for KYT process.

Responses

Request samples

Content type
application/json
Example
{
  • "end_to_end_id": "PA-ecf87cf814cd4d95a970ac7e8d7e7ef3",
  • "client_payment_id": "string",
  • "recipient": {
    },
  • "payment_instrument": {
    },
  • "recipient_id": "b6731cb5-d462-49ea-afb8-7933b670b560",
  • "payment_instrument_id": "9107be81-0e98-4406-8bb9-e4d1c6795a62",
  • "source_account_id": "75fca71f-6b38-4768-804d-ffb93d0aa579",
  • "operation": {
    },
  • "exchange_rate_id": "516fcd42-a1e5-4a7c-9b28-b7869f5f651b",
  • "carded_rate_id": "7a29f3e3-7ccc-4f67-af1d-6df58596d191",
  • "kyt": {
    }
}

Response samples

Content type
application/json
{
  • "end_to_end_id": "PA-ecf87cf814cd4d95a970ac7e8d7e7ef3",
  • "client_payment_id": "string",
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "initiated_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "status": "string",
  • "fees": {
    },
  • "exchange_rate": {
    },
  • "recipient_id": "b6731cb5-d462-49ea-afb8-7933b670b560",
  • "payment_instrument_id": "9107be81-0e98-4406-8bb9-e4d1c6795a62"
}

Get payment information by its ID

Authorizations:
OAuth2
path Parameters
id
required
string <uuid>

Responses

Response samples

Content type
application/json
{
  • "end_to_end_id": "PA-ecf87cf814cd4d95a970ac7e8d7e7ef3",
  • "client_payment_id": "string",
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "initiated_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "status": "string",
  • "fees": {
    },
  • "exchange_rate": {
    },
  • "recipient_id": "b6731cb5-d462-49ea-afb8-7933b670b560",
  • "payment_instrument_id": "9107be81-0e98-4406-8bb9-e4d1c6795a62"
}

Update payment details

Update Payment after it has been stopped due to insufficient KYC/B/T information. This call allows updating only KY related information. If additional recipient information is required please use PATCH Recipient operation.

This operation is allowed only for transactions in KYT pending status.

Authorizations:
OAuth2
path Parameters
id
required
string <uuid>
Request Body schema: application/json
required
Array of objects (SupportingDocument)

Documents that will be considered as proof for the payment.

This field may be required depending on your KYT settings. Consult the discovery endpoint for more information.

This field can be updated only for payments with pending KYT for which a request for additional documents was issued.

exchange_rate_id
string <uuid>

New exchange rate ID in case previous one expired. New exchange rate must use the same parameters as original one. Use /v2/exchange-rates/{id}/refresh endpoint to obtain new exchange rate.

This field can be updated only for payments with expired exchange rate.

Responses

Request samples

Content type
application/json
{
  • "supporting_documents": [
    ],
  • "exchange_rate_id": "516fcd42-a1e5-4a7c-9b28-b7869f5f651b"
}

Response samples

Content type
application/json
{
  • "end_to_end_id": "PA-ecf87cf814cd4d95a970ac7e8d7e7ef3",
  • "client_payment_id": "string",
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "initiated_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "status": "string",
  • "fees": {
    },
  • "exchange_rate": {
    },
  • "recipient_id": "b6731cb5-d462-49ea-afb8-7933b670b560",
  • "payment_instrument_id": "9107be81-0e98-4406-8bb9-e4d1c6795a62"
}

Payments instruments

Get list of payment instruments

Authorizations:
OAuth2
query Parameters
recipient_id
string <uuid>

ID of the recipient to get payment instruments belonging to this recipient.

page_number
integer >= 1
Default: 1

Page number.

page_size
integer [ 1 .. 100 ]
Default: 20

Page size.

Responses

Response samples

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

Get list of payment instruments

Authorizations:
OAuth2
query Parameters
recipient_id
string <uuid>

ID of the recipient to get payment instruments belonging to this recipient.

page_number
integer >= 1
Default: 1

Page number.

page_size
integer [ 1 .. 100 ]
Default: 20

Page size.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create a payment instrument

Authorizations:
OAuth2
Request Body schema: application/json
One of
recipient_id
required
string <uuid>

ID of an existing recipient that this instrument belongs to. It is required for new payment instrument creation.

category
required
string (PaymentInstrumentCategory)
Enum: "BankAccount" "MobileWallet" "CashPickup" "Card"
currency
string
mobile_number
required
string
phone_operator
string
country
string

If a country is provided, pre-validation of the request is performed.

Responses

Request samples

Content type
application/json
Example
{
  • "recipient_id": "b6731cb5-d462-49ea-afb8-7933b670b560",
  • "category": "BankAccount",
  • "currency": "string",
  • "mobile_number": "string",
  • "phone_operator": "string",
  • "country": "string"
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08"
}

Get payment instrument by its ID

Authorizations:
OAuth2
path Parameters
id
required
string <uuid>

Responses

Response samples

Content type
application/json
Example
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "category": "BankAccount",
  • "currency": "string",
  • "mobile_number": "string",
  • "phone_operator": "string"
}

Exchange

Get exchange rate information by its ID

Authorizations:
OAuth2
path Parameters
id
required
string <uuid>

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "source_amount": {
    },
  • "target_amount": {
    },
  • "expiration_date": "2019-08-24T14:15:22Z"
}

Get new exchange rate based on already existing rate.

Authorizations:
OAuth2
path Parameters
id
required
string <uuid>

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "source_amount": {
    },
  • "target_amount": {
    },
  • "expiration_date": "2019-08-24T14:15:22Z"
}

Request exchange rate information.

The exchange rate can be later used to initiate a new payment. Obtaining the exchange rate before payment is optional.

Authorizations:
OAuth2
Request Body schema: application/json
required
source_account_id
string <uuid>

ID of the account to use as source of funds.

Provide either source or target amount to receive the opposite value.

source_currency
string <iso-4217> = 3 characters

Currency of the source amount.

This field is required only if both source_amount and source_account_id are NOT provided. This is useful if you're not using currency exchange markup based on payer segmentation (ie high volume business payers having different rates than individuals).

object (Amount)
object (Amount)
recipient_instrument_id
string

Represents recipient's payment instrument id of already existent entity.

This field is for backward compatibility and will be removed in the future. Please use payment_instrument_category instead.

payment_instrument_category
string (PaymentInstrumentCategory)
Enum: "BankAccount" "MobileWallet" "CashPickup" "Card"
payment_type
string (PaymentType)
Enum: "B2B" "B2P" "P2B" "P2P"
target_currency
string <iso-4217> = 3 characters
destination_country
required
string <iso-3166-alpha-2>

Destination country for the payment. 3166-1 alpha-2 value. Hint: It is GB, not UK.

Responses

Request samples

Content type
application/json
{
  • "source_account_id": "75fca71f-6b38-4768-804d-ffb93d0aa579",
  • "source_currency": "EUR",
  • "source_amount": {
    },
  • "target_amount": {
    },
  • "recipient_instrument_id": "string",
  • "payment_instrument_category": "BankAccount",
  • "payment_type": "B2B",
  • "target_currency": "GBP",
  • "destination_country": "GB"
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "source_amount": {
    },
  • "target_amount": {
    },
  • "expiration_date": "2019-08-24T14:15:22Z"
}

Confirm exchange rate

Confirm the exchange rate to lock it for future use. This operation is required if you want to use the exchange rate for a payment after exchange rate quote expires. This is valid only for quoted rates program configurations.

This operation will block funds on the source account. The funds will be release automatically if the payment is not initiated within the timeframe configured for your program.

If needed you can cancel the quote to unblock funds earlier.

Authorizations:
OAuth2
Request Body schema: application/json
required
exchange_rate_id
string <uuid>

ID of the exchange rate to confirm.

Responses

Request samples

Content type
application/json
{
  • "exchange_rate_id": "516fcd42-a1e5-4a7c-9b28-b7869f5f651b"
}

Cancel exchange rate

Cancel the exchange rate to unblock funds on the source account. This operation is allowed only for exchange rates that have been confirmed.

Authorizations:
OAuth2
Request Body schema: application/json
required
exchange_rate_id
string <uuid>

ID of the exchange rate to cancel.

Responses

Request samples

Content type
application/json
{
  • "exchange_rate_id": "516fcd42-a1e5-4a7c-9b28-b7869f5f651b"
}

Get carded exchange rates

Authorizations:
OAuth2

Responses

Response samples

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

Accounts

Get list of payment accounts

Authorizations:
OAuth2
query Parameters
page_number
integer >= 1
Default: 1

Page number.

page_size
integer [ 1 .. 100 ]
Default: 20

Page size.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get list of payment accounts

Authorizations:
OAuth2
query Parameters
page_number
integer >= 1
Default: 1

Page number.

page_size
integer [ 1 .. 100 ]
Default: 20

Page size.

Responses

Response samples

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

Recipients

Get list of recipients

Authorizations:
OAuth2
query Parameters
page_number
integer >= 1
Default: 1

Page number.

page_size
integer [ 1 .. 100 ]
Default: 20

Page size.

id
string <uuid>

ID of the recipient to get.

external_id
string

External ID of the recipient to get.

Responses

Response samples

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

Get list of recipients

Authorizations:
OAuth2
query Parameters
page_number
integer >= 1
Default: 1

Page number.

page_size
integer [ 1 .. 100 ]
Default: 20

Page size.

id
string <uuid>

ID of the recipient to get.

external_id
string

External ID of the recipient to get.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create a recipient

Authorizations:
OAuth2
Request Body schema: application/json
One of
type
required
string (Type)
Enum: "Person" "Business"
external_id
string

ID from external system.

email
string <email>
first_name
required
string
last_name
required
string
middle_name
string
mobile_number
string
dob
string <date>
string
object (Address)
object (IdentityDocument)

Responses

Request samples

Content type
application/json
Example
{
  • "type": "Person",
  • "external_id": "string",
  • "email": "user@example.com",
  • "first_name": "string",
  • "last_name": "string",
  • "middle_name": "string",
  • "mobile_number": "string",
  • "dob": "2019-08-24",
  • "occupation": "general_worker",
  • "registration_address": {
    },
  • "identity_document": {
    }
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08"
}

Get recipient information by its ID

Authorizations:
OAuth2
path Parameters
id
required
string <uuid>

Responses

Response samples

Content type
application/json
Example
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "type": "Person",
  • "external_id": "string",
  • "email": "user@example.com",
  • "first_name": "string",
  • "last_name": "string",
  • "middle_name": "string",
  • "mobile_number": "string",
  • "dob": "2019-08-24",
  • "occupation": "general_worker",
  • "registration_address": {
    },
  • "identity_document": {
    }
}

Update a recipient

Authorizations:
OAuth2
path Parameters
id
required
string <uuid>
Request Body schema: application/json
One of
type
required
string
Value: "Person"
object (Address)
object (IdentityDocument)

Responses

Request samples

Content type
application/json
Example
{
  • "type": "Person",
  • "registration_address": {
    },
  • "identity_document": {
    }
}

Response samples

Content type
application/json
Example
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "type": "Person",
  • "external_id": "string",
  • "email": "user@example.com",
  • "first_name": "string",
  • "last_name": "string",
  • "middle_name": "string",
  • "mobile_number": "string",
  • "dob": "2019-08-24",
  • "occupation": "general_worker",
  • "registration_address": {
    },
  • "identity_document": {
    }
}

Delete a recipient

This operation is allowed only for recipients without payments (past, pending, scheduled or recurring)

Authorizations:
OAuth2
path Parameters
id
required
string <uuid>

Responses

Get recipient amount limits

This operation fetches amount limits for recipient.

Authorizations:
OAuth2
path Parameters
id
required
string <uuid>

The ID of the recipient for which to provide payment limits

query Parameters
payment_type
required
string (PaymentType)
Enum: "B2B" "B2P" "P2B" "P2P"
country
required
string <iso-3166-alpha-2>
Example: country=GB

Country for the payment. ISO-3166-1 alpha-2 value. Hint: It is GB, not UK.

instrument_category
required
string (PaymentInstrumentCategory)
Enum: "BankAccount" "MobileWallet" "CashPickup" "Card"
currency
required
string <iso-4217> = 3 characters
Example: currency=EUR

The currency for which the limit should be provided. If there is no limit set in specified currency then limit will be returned in the base currency set for this account. Currency format ISO-4217

Responses

Response samples

Content type
application/json
{
  • "minimum": {
    },
  • "maximum": {
    }
}

Payers

Create a payer

Payer accounts will be created automatically however depending on configurations of your account, the payer may first be subject to KYC or KYB checks.

Authorizations:
OAuth2
Request Body schema: application/json
One of
type
required
string
Enum: "Business" "Person"
external_id
string

ID from external system.

first_name
required
string
middle_name
string
last_name
required
string
phone_number
string
object (Address)
nationality
string
government_id
string
date_of_birth
string <date>
source_of_income
string
email
string
place_of_birth
string
string
relationship_with_beneficiary
string
employer_name
string
employer_country
string <iso-3166-alpha-2>

Country of registration. 3166-1 alpha-2 value. Hint: It is GB, not UK.

employer_industry
string

Responses

Request samples

Content type
application/json
Example
{
  • "type": "Business",
  • "external_id": "string",
  • "first_name": "string",
  • "middle_name": "string",
  • "last_name": "string",
  • "phone_number": "string",
  • "registration_address": {
    },
  • "nationality": "string",
  • "government_id": "string",
  • "date_of_birth": "2019-08-24",
  • "source_of_income": "string",
  • "email": "string",
  • "place_of_birth": "string",
  • "occupation": "general_worker",
  • "relationship_with_beneficiary": "string",
  • "employer_name": "string",
  • "employer_country": "PL",
  • "employer_industry": "string"
}

Response samples

Content type
application/json
Example
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "accounts": [
    ],
  • "type": "Business",
  • "external_id": "string",
  • "first_name": "string",
  • "middle_name": "string",
  • "last_name": "string",
  • "phone_number": "string",
  • "registration_address": {
    },
  • "nationality": "string",
  • "government_id": "string",
  • "date_of_birth": "2019-08-24",
  • "source_of_income": "string",
  • "email": "string",
  • "place_of_birth": "string",
  • "occupation": "general_worker",
  • "relationship_with_beneficiary": "string",
  • "employer_name": "string",
  • "employer_country": "PL",
  • "employer_industry": "string"
}

Get payer by its ID

Authorizations:
OAuth2
path Parameters
id
required
string <uuid>

Responses

Response samples

Content type
application/json
Example
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "accounts": [
    ],
  • "type": "Business",
  • "external_id": "string",
  • "first_name": "string",
  • "middle_name": "string",
  • "last_name": "string",
  • "phone_number": "string",
  • "registration_address": {
    },
  • "nationality": "string",
  • "government_id": "string",
  • "date_of_birth": "2019-08-24",
  • "source_of_income": "string",
  • "email": "string",
  • "place_of_birth": "string",
  • "occupation": "general_worker",
  • "relationship_with_beneficiary": "string",
  • "employer_name": "string",
  • "employer_country": "PL",
  • "employer_industry": "string"
}

Update a payer

Authorizations:
OAuth2
path Parameters
id
required
string <uuid>
Request Body schema: application/json
One of
type
required
string
Enum: "Business" "Person"
external_id
string

ID from external system.

first_name
required
string
middle_name
string
last_name
required
string
phone_number
string
object (Address)
nationality
string
government_id
string
date_of_birth
string <date>
source_of_income
string
email
string
place_of_birth
string
string
relationship_with_beneficiary
string
employer_name
string
employer_country
string <iso-3166-alpha-2>

Country of registration. 3166-1 alpha-2 value. Hint: It is GB, not UK.

employer_industry
string

Responses

Request samples

Content type
application/json
Example
{
  • "type": "Business",
  • "external_id": "string",
  • "first_name": "string",
  • "middle_name": "string",
  • "last_name": "string",
  • "phone_number": "string",
  • "registration_address": {
    },
  • "nationality": "string",
  • "government_id": "string",
  • "date_of_birth": "2019-08-24",
  • "source_of_income": "string",
  • "email": "string",
  • "place_of_birth": "string",
  • "occupation": "general_worker",
  • "relationship_with_beneficiary": "string",
  • "employer_name": "string",
  • "employer_country": "PL",
  • "employer_industry": "string"
}

Response samples

Content type
application/json
Example
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "accounts": [
    ],
  • "type": "Business",
  • "external_id": "string",
  • "first_name": "string",
  • "middle_name": "string",
  • "last_name": "string",
  • "phone_number": "string",
  • "registration_address": {
    },
  • "nationality": "string",
  • "government_id": "string",
  • "date_of_birth": "2019-08-24",
  • "source_of_income": "string",
  • "email": "string",
  • "place_of_birth": "string",
  • "occupation": "general_worker",
  • "relationship_with_beneficiary": "string",
  • "employer_name": "string",
  • "employer_country": "PL",
  • "employer_industry": "string"
}

Get payer amount limits

This operation fetches amount limits for payer.

Authorizations:
OAuth2
path Parameters
id
required
string <uuid>

The ID of the payer for which to provide payment limits

query Parameters
payment_type
required
string (PaymentType)
Enum: "B2B" "B2P" "P2B" "P2P"
country
required
string <iso-3166-alpha-2>
Example: country=GB

Country for the payment. ISO-3166-1 alpha-2 value. Hint: It is GB, not UK.

instrument_category
required
string (PaymentInstrumentCategory)
Enum: "BankAccount" "MobileWallet" "CashPickup" "Card"
currency
required
string <iso-4217> = 3 characters
Example: currency=EUR

The currency for which the limit should be provided. If there is no limit set in specified currency then limit will be returned in the base currency set for this account. Currency format ISO-4217

Responses

Response samples

Content type
application/json
{
  • "minimum": {
    },
  • "maximum": {
    }
}

Get payer by its ID or external ID

This endpoint allows to retrieve payer by its ID or external ID. Either id or external_id must be provided. If both are provided then they both must match the same payer.

Authorizations:
OAuth2
query Parameters
id
string <uuid>

ID of the payer to get.

external_id
string

External ID of the payer to get.

Responses

Response samples

Content type
application/json
Example
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "accounts": [
    ],
  • "type": "Business",
  • "external_id": "string",
  • "first_name": "string",
  • "middle_name": "string",
  • "last_name": "string",
  • "phone_number": "string",
  • "registration_address": {
    },
  • "nationality": "string",
  • "government_id": "string",
  • "date_of_birth": "2019-08-24",
  • "source_of_income": "string",
  • "email": "string",
  • "place_of_birth": "string",
  • "occupation": "general_worker",
  • "relationship_with_beneficiary": "string",
  • "employer_name": "string",
  • "employer_country": "PL",
  • "employer_industry": "string"
}

Compliance

Upload new compliance document

Use this method to upload documents.

Supported file types are: PDF, PNG, JPEG.

Authorizations:
OAuth2
Request Body schema:
string <binary>

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08"
}

Events

Payment event

Post payment related events.

Payall will retry to deliver the event for 24 hours until receiving HTTP response code 200. After 24 hours there will be no further attempts to deliver the event. Attempts are repeated as follows:

  • Every 10 seconds for first minute
  • Every minute for the following 9 minutes
  • Every 10 minutes for the following 50 minutes
  • Every hour for the following 23 hours

Payall expects the response within 3 seconds. Lack of response within 3 seconds is considered to be failed delivery attempt.

No response body is expected.

Authorizations:
ApiKeyAuth
path Parameters
event_type
required
string
Enum: "StatusChange" "Documents"
tenant_id
required
string
header Parameters
X-Attempt-Number
required
integer

Delivery attempt number. First attempt value is 1.

Request Body schema: application/json
One of
status
required
string
Enum: "Created" "PendingCompliance" "Completed" "Declined" "ExchangeRateExpired" "PendingSettlement" "PendingClearingInstitution" "PendingFinance" "PendingServiceProvider" "PendingDocument"

ExchangeRateExpired status means that an action by the payer is required in order to approve new exchange rate in order to proceed with the payment.

Exchange rate will usually expire for payments that will have to undergo additional KYT checks. Event related to this status will be emitted only after the KYT process finishes meaning that the date of the event and exchange rate expiry date will not match.

PendingSettlement status means that the payment can be processed but needs the settlement account to be funded first. This status will be applicable depending on configuration of the originating institution program.

In case you are controlling the settlement funding on your side this status informs you that you need to fund the settlement account in order to process the payment.

PendingClearingInstitution status means that the payment was processed on our side and sent to the clearing institution.

PendingFinance status means that the payment requires manual approval by the finance officer of the originating institution. This status will be applicable depending on configuration of the originating institution program.

PendingServiceProvider status means that the payment has been processed on our side and sent to the service provider for further processing before sending to the Clearing Institution. This status will be applicable depending on configuration of the originating institution program.

PendingDocument status means that the payment requires additional documents to be uploaded before it can be processed. Refer to the DocumentsEvent and /v2/documents endpoint for more details.

id
required
string <uuid>

Id of the payment in Payall system.

client_payment_id
required
string

External reference provided when initiating the payment.

timestamp
required
string <date-time>

The date-time of the event.

Notation as defined by RFC 3339, section 5.6, for example, 2017-07-21T17:32:28Z

code
string

Optional status code associated with the event. For example in case of rejected payments it will identify the reason of rejection.

Responses

Request samples

Content type
application/json
Example
{
  • "status": "Created",
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "client_payment_id": "string",
  • "timestamp": "2019-08-24T14:15:22Z",
  • "code": "string"
}

Exchange rates

Post carded exchange rates

Authorizations:
ApiKeyAuth
path Parameters
event_type
required
string
Value: "Publish"

Event type for the rates

tenant_id
required
string

Tenant identifier

Request Body schema: application/json
required

Currency exchange rates data

required
Array of objects (CardedRate)

Responses

Request samples

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

Tokenization

Tokenize card details

Tokenize provided card details. Returns a token that can be used to reference the card in other API methods.

This endpoint is not idempotent.

Card number needs to be stripped of any non-digit characters before encrypting. Expected pattern match is ^[1-9][0-9]{7,19}$.

We recommend validation of card number using Luhn algorithm before encrypting using Luhn algorithm.

We don't do card brand validation during this call. Any brand will be accepted by the vault but the payment may fail if the token is used for a payment with a vendor that does not support given brand.

path Parameters
clientId
required
string <uuid>
Request Body schema: application/json
required
card_number
required
string

Encrypted card number using client public key.

Card number needs to be stripped of any non-digit characters before encrypting. Expected pattern match is ^[1-9][0-9]{7,19}$.

We recommend validation of card number using Luhn algorithm before encrypting using Luhn algorithm.

expiration_date
string

ISO/EIC 7813 Expiration date of the card

Responses

Request samples

Content type
application/json
{
  • "card_number": "ZiudIxi1h3P57k8OwmfOx1wpqIBeTGMu560uvdQoGYm2wfg/AIj8QkFpi2XTaCT4sO9drQvLSH9rSk3njQOGpSUmCzlPsA6ahG7Mg/0fMP2V6ahdMUmgmZPU1KVqL48p0pwjgSG6pTbLj6ROQFpPNkhs3ilrrQccKg7FamV34WC6hzEVyVRreR54LQeOAIFX5zQLOD4ldV/z8ikYdktKiFMkghQnF2oqzsd/rNTkL2DwzWTahgiA6gYZpoOhXt4rr1KoENC4hV4yT7iefyIFCGQu7EzeD15XB3v2+Q0Xj9ifOynADek3Mjxn6Bmg7fELGuUEkkxFgeLZrxrEcqAFbg==",
  • "expiration_date": "12/30"
}

Response samples

Content type
application/json
{
  • "token": "f7b3b3b4-0b3d-4b3b-8b3b-3b3b3b3b3b3b",
  • "created_at": "2021-03-03T16:27:54.378693Z",
  • "masked_pan": "5425 **** **** 8113",
  • "client_id": "f0396c8e-a87b-402d-9692-520cbc0947b5",
  • "brand": "Visa"
}

Get configuration

Get encryption key and parameters for a specific id

path Parameters
id
required
string <uuid>

Responses

Response samples

Content type
application/json
{
  • "encryption_key": "MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAuNernozTqNnb17qzYof4sYlB7QueXE+7l8B2pa4kaNwGfsquMpD9S6hXKUY2zKlCSovs811+rNWt1x6oxj3H3RSOH6J8RlG+29cDF5OXySeORON8dmPLCtZ4uXMQ4JYtlAlcPNgKJgQmnrnQJ4btb+S3FYZJ0rJyx+wpRJith4BUl0/QA3ldfLQAeWWf+6wXXhkB2n4u0zBGYd3v+L/TdqHDDrJuLVFkG2tXaBvNTQETwyPHJA06cAeqSyHneKb1RIznYL/QxUBoPAfTYdrI9cV5gUJ6bolFMrzSU9QlOR/SEjtXWjEE9sH39QLPqAJvijT1XUDNJOIeFB4E+pxGrQIDAQAB",
  • "created_at": "2019-08-24T14:15:22Z",
  • "encryption_algorithm": "RSAES_OAEP_SHA_256",
  • "require_expiration_date": false
}