Payall M2M Authentication API (2.0)

Payall platform supports different flows depending on customer needs. Please consult the flows relevant to your operational model with our team first.

This is the most common scenario in which Payall takes care of the onboarding process of the payers. In this scenario all payments are made on behalf of payers that have been previously onboarded to Payall platform.

In this flow payers are being onboarded by the client and all the KYB/KYC data is sent to Payall platform via API. In this scenario all payments are made on behalf of payers that have been previously onboarded to Payall platform.

In this scenario payments can be made on behalf of payers that have not been onboarded to Payall platform. For this scenario the API consumer is responsible for providing all the relevant payer details required for selected payment channel with each payment call.

Our api supports payments with both implicit and explicit exchange rates. Use implicit exchange rates when the exact exchange rate of the payment does not need to be approved. Those would be usually cases of automated systems that make scheduled or unattended payments without user interactions.

For implicit exchange rate you only need one call to single-payment endpoint. Our system will immediately process the payment using the best exchange rate available at that moment in time. Response from the single-payment call will contain exchange rate information that you can check at any time.

Explicit exchange rate flow is best suited for scenarios in which the payer wants or needs to accept the exchange rate of the payment before the payment is processed. Please note that depending on the payment processor, the payment channel and your contract agreement you may expect different exchange rate expiration times ranging from 60 seconds to few hours. Take that into account when designing user flows on your side.

Refer to exchange-rates API endpoint for more information on how to obtain exchange rates and single-payment endpoint on how to initiate a payment with specific exchange rate.

In case of unfortunate situation of delaying the payment due to insufficient KYC/KYB/KYT data or any other circumstances that would lead to expiry of the exchange rate used during payment initiation (applies to explicit exchange rate flow) our system will emit an event when the payment is ready to process allow you to reinitialise exchange rate approval process on your side.

After new exchange rate is approved you can PATCH your payment by providing new exchange rate ID.

In some cases in order to process a payment there may be a compliance requirement to provide additional documents. This is usually applies to payments of bigger amounts or payments to certain countries. Consult your contract agreement with Payall to find out in which scenarios this applies for your payments.

Payment with mandatory document upload

For payments that require additional documents you will have to first upload the documents and then initiate the payment. This is a two-step process. Consult documents API endpoint for more information on how to upload documents.

Payment with KYT request for documents

In some cases payment processors or KYT rules may trigger a request for additional documents to be provided for your payment. In such cases you will receive a notification with a list of documents that are required to process the payment. Each document will have a unique case UUID that you need to use when calling document upload endpoint.

It is the same endpoint as in the case of mandatory document upload. Consult documents API endpoint for more information on how to upload documents.

Document upload through Payall UI

Additional documents can also be provided through Payall UI either by the payer or by the backoffice users. Consult your contract agreement with Payall to find out which UI options are available for your organisation.

Failed KYT document checks

In case of failed document checks the process of requesting new documents will repeat. Payments that did not receive additional documents in time will be cancelled automatically. Consult your program configuration for more information on how long your payment will wait for documents.

This API uses OAuth 2 with the Client Credentials flow (defined in OAuth 2.0 RFC 6749, section 4.4). In order to gain access token you need to pass along Client ID and Client Secret to authenticate /v2/oauth/token endpoint.

1. Your application authenticates with the Authorisation endpoint using its Client ID and Client Secret (/v2/oauth/token endpoint).
2. Authorisation Server validates the Client ID and Client Secret.
3. Authorisation Server responds with an Access Token.
4. Your application can use the access token to call an API on behalf of itself.
5. The API responds with requested data.

The Authorization header for the token request requires you to apply base64 encoding to the {client_id}:{client_secret} string. Please note that when generating the encoded string via command line you may end up with unexpected newline characters that will not let you obtain the access token. In that case make sure to use the following command for testing:

echo -n "{client_id}:{client_secret}" | base64

Depending on your PCI compliance level and the way you handle card data, Payall offers two ways to tokenize sensitive payment card data like PAN (Primary Account Number) / card number.

For customers who want to limit their PCI exposure and associated compliance requirements, Payall offers a PCI Vault iframe solution. This solution is suitable for customers who do not have a PCI DSS certification and want to avoid handling sensitive card data themselves.

For customers who have a valid PCI DSS certification and want to handle card data on their side, Payall offers a Tokenization API. This API allows you to tokenize sensitive payment card data prior to initiating a payment. Tokens are used to represent payment card data in a secure way. The token can be used to make payments without exposing the actual card data.

When using Payall PCI Vault iframe your systems do not have access to raw PAN anywhere throughout the process. All sensitive operations related to collecting, transmitting and storing of sensitive data are managed by Payall. In this case the PCI exposure to you is minimal, however we still encourage you to get yourself familiar with PCI DSS and fill in the PCI Self Assessment Questionnaire A when working with cards and using our Vault.

Script initialisation

Embed the following script in your HTML page to initialise the Payall Vault client:

<script src="https://static.sandbox.payall.com/vault/js/dist/vault-client.js"></script>

Prepare the HTML element to hold the iframe:

<div id="payall-vault"></div>

Initialise the client with the following JavaScript code. Use clientId value provided by our integration team. The provided ID below is just a sample and will not work:

const clientId = 'f0396c8e-a87b-402d-9692-520cbc000000';
const vault = PayallVault.init(clientId, 'payall-vault');

Invoking PayallVault.init() will immediately generate an iframe inside the provided element ID. The frame is generated with the following style:

 iframe.style.width = "100vw";
 iframe.style.height = '100vh';
 iframe.style.border = "none";

Attach event handlers to handle the events emitted by the UI within the iframe. Key events are PanTokenized , Cancel and Error:

vault.addEventHandler('PanTokenized', function (event) {
    // Put your busines logic here.
    console.log('Received PanTokenized event:', event);
    // You should store the token in your system for later use.
});

valut.addEventHandler('Error', function (event) {
    // Handle the error event here.
    console.error('Error event:', event);
});

vault.addEventHandler('Cancel', function (event) {
  // This means that the user clicked "Cancel" button and you should react accordingly.
    console.log('Received Cancel event:', event);
  document.getElementById('payall-vault').innerHTML = '';
});

List of available events

PayallVault class exposes the list available events under Events property:

console.log(PayallVault.Events);
// Set {"PanTokenized", "Error", "Cancel"}

Full HTML example

Putting things together

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <title>Demo iframe launcher</title>
    <script src="https://static.sandbox.payall.com/vault/js/dist/vault-client.js"></script>
    <!--
        This is just a demo implementation of the client-side vault initialization.
        This part is not on Payall to implement - it should be a part
        of the client-side application.

        This is just meant for testing only.
    -->
    <script>
        window.onload = function() {

            console.log("Available events from the vault:");
            console.log(PayallVault.Events);

            document.getElementById('launch-iframe').addEventListener('click', function () {
                const clientId = document.getElementById('clientId').value;
                let vault = PayallVault.init(clientId, 'payall-vault');

                vault.addEventHandler('PanTokenized', function (event) {
                    console.log('Received PanTokenized event:', event);
                    document.getElementById('iframe-messages').innerText
                        += "\nPanTokenized event:" + JSON.stringify(event.message);
                });

                vault.addEventHandler('Cancel', function (event) {
                    console.log('Received Cancel event:', event);
                    document.getElementById('iframe-messages').innerHTML = '';
                    document.getElementById('payall-vault').innerHTML = '';
                });

                vault.addEventHandler('Error', function (event) {
                    console.log('Received Error event:', event);
                    document.getElementById('iframe-messages').innerText
                        += "\nError event:" + JSON.stringify(event.message);

                    if(event.message.message === 'Configuration error') {
                        document.getElementById('payall-vault').innerHTML = '';
                    }
                });
            });
        }
    </script>
</head>
<body>
    <label for="clientId">Client ID:</label>
    <input type="text" id="clientId" value="f0396c8e-a87b-402d-9692-520cbc000000">
    <button id="launch-iframe">Launch iframe</button>
    <div id="iframe-messages"></div>
    <div id="payall-vault"></div>
</body>
</html>

Additional options

Translations

Translations can be provided to the iframe to localize the UI. The vault supports any language that is supported by the browser. The default language is English. List of available translation keys is available under static field PayallVault.TranslationKeys.

console.log("Available translation keys:", PayallVault.TranslationKeys);

All keys are optional. If a key is not provided, the default value will be used.

[
    'panLabel',
    'expiryLabel',
    'cancelLabel',
    'encryptLabel',
    'expiryDateInPast',
    'cardNumberEmpty',
    'invalidCardNumber',
    'expiryDateRequired',
    'invalidNumericValues',
    'invalidMonth',
    'genericError',
]

The vault expect to receive translations as Map<string, string>.
The following example shows how to provide translations:

const es_translations = new Map([
    ['panLabel',            "Número de Tarjeta de Crédito"],
    ['expiryLabel',         "Fecha de Expiración"],
    ['cancelLabel',         "Cancelar"],
    ['encryptLabel',        "Encriptar"],
    ['expiryDateInPast',    "La fecha de expiración no puede ser en el pasado"],
    ['cardNumberEmpty',     "El número de tarjeta no puede estar vacío"],
    ['invalidCardNumber',   "Número de tarjeta inválido"],
    ['expiryDateRequired',  "La fecha de expiración es requerida"],
    ['invalidNumericValues',"Valores numéricos inválidos"],
    ['invalidMonth',        "Mes inválido"],
    ['genericError',        "Error genérico"],
]);

// This is just a sample client ID. Replace it with your own.
const clientId = 'f0396c8e-a87b-402d-9692-520cbc000000';
const vault = PayallVault.init(
    clientId, 'payall-vault',
    {
        translations: es_translations
    }
);

Text direction

Some languages require RTL (right-to-left) text direction.
The vault supports RTL text direction via the dir option.
Default value is ltr (left-to-right).

// This is just a sample client ID. Replace it with your own.
const clientId = 'f0396c8e-a87b-402d-9692-520cbc000000';
const vault = PayallVault.init(
    clientId, 'payall-vault',
    {
        translations: he_translations,
        dir: 'rtl',
    }
);

Hiding Cancel button

It is possible to hide the Cancel button by setting the hideCancelButton option to true.

// This is just a sample client ID. Replace it with your own.
const clientId = 'f0396c8e-a87b-402d-9692-520cbc000000';
const vault = PayallVault.init(
    clientId, 'payall-vault',
    {
        hideCancelButton: true
    }
);

If you collect card numbers on your side, you need to interact with the Payall Vault API to tokenize sensitive payment card data prior to initiating a payment. Tokens are used to represent payment card data in a secure way. The token can be used to make payments without exposing the actual card data. See PCI Vault Tokenization API for more information.

Please note that in order to use the Vault API and encrypt sensitive PAN data on your side you need to have a valid PCI DSS certification. Otherwise, you can use the Payall PCI Vault iframe solution instead.

Payall is certified PCI DSS Level 1 Service Provider.

Encryption

The Payall Vault API uses asymmetric encryption to secure the PAN data. You are required to encrypt the PAN using a public key and algorithm provided by Payall in response to the GET Configuration request.

Note that keys may be rotated without prior notice and you should always fetch the latest configuration before encrypting the PAN.

At the time of writing the algorithm used is RSAES-OAEP with SHA-256 hash.

Validation

Prior to sending the PAN to the Payall Vault API you should validate and sanitize the PAN data. The PAN should be a valid card number - we suggest to verify it using Luhn algorithm.

Sanitization

Before encrypting the PAN you should remove all non-numeric characters including any leading and trailing spaces. Expected pattern match is ^[1-9][0-9]{7,19}$.

When interacting with our API you may encounter the following error responses:

{
  "code": "PUB4004",
  "message": "The payer type is missing or incorrect.",
  "timestamp": "2025-02-03T15:07:57.735569007Z"
}

In some cases, when the error is caused by a 3rd party system, the error code will be PUB9001 and will contain additional information from the external system:

{
  "code": "PUB9001",
  "message": "External system error.",
  "timestamp": "2025-02-03T15:07:57.735569007Z",
  "data": {
    "code": "150008",
    "message": "Internal Configuration Error."
  }
}

The following table lists the error codes that the API can return:

Error code	Message
PUB1	General or unhandled error. Please contact administrator.
PUB2	Security error. Please contact administrator.
PUB3	Not found error. See error message for details.
PUB4	External system client error. Please contact administrator.
PUB5	External system server error. Please contact administrator.
PUB20	Data validation error. Please contact administrator.
PUB21	Data validation error.
PUB6	External 500 error. Please contact administrator.
PUB7	Unauthorized access to external service. Please contact administrator.
PUB8	Forbidden access to external service. Please contact administrator.
PUB9	Mapping payload exception. Please contact administrator.
PUB10	Method not allowed. Please contact administrator.
PUB1001	System configuration error. Please contact administrator.
PUB1010	The payment channel was not found. Please contact administrator.
PUB1011	Payment channel misconfiguration. Please contact administrator.
PUB1021	Payment schema misconfiguration. Please contact administrator.
PUB2001	Access control error. Please contact administrator.
PUB2002	Access denied. Please contact administrator.
PUB4001	General input validation error. See error message for details.
PUB4002	Payload unreadable. See error message for details.
PUB4003	Data binding error. See error message for details.
PUB4004	The payer type is missing or incorrect
PUB4005	The business payer's legal name is missing
PUB4006	The business payer's incorporation country is missing
PUB4007	The business payer's incorporation country is incorrect
PUB4008	The business payer's registration number is missing
PUB4009	The business payer's registration address is missing
PUB4010	The business payer's registration date is incorrect
PUB4011	The business payer's phone number is incorrect
PUB4012	The person's first name is missing
PUB4013	The person's last name is missing
PUB4014	The person's phone number is missing
PUB4015	The person's phone number is incorrect
PUB4016	The person's registration address is missing
PUB4017	The person's government ID is missing
PUB4018	The person's date of birth is missing
PUB4019	The person's date of birth is incorrect
PUB4020	The person's email is missing
PUB4021	The recipient type is missing or incorrect
PUB4022	The business recipient's legal name is missing
PUB4023	The business recipient's trade name is missing
PUB4024	The business recipient's phone number is missing
PUB4025	The business recipient's phone number is incorrect
PUB4026	The business recipient's email is missing
PUB4027	The business recipient's registration number is missing
PUB4028	The business recipient's registration address is missing
PUB4029	The business recipient's incorporation country is missing
PUB4030	The business recipient's incorporation country is incorrect
PUB4031	The person's first name is missing
PUB4032	The person's last name is missing
PUB4033	The person's mobile number is missing
PUB4034	The person's mobile number is incorrect
PUB4035	The person's email is missing
PUB4036	The person's date of birth is incorrect
PUB4037	The person's registration address is missing
PUB4038	The city in the registration address is missing
PUB4039	The city in the registration address is incorrect
PUB4040	The country in the registration address is missing
PUB4041	The country in the registration address is incorrect
PUB4042	The street address in the registration address is missing
PUB4043	The street address in the registration address is incorrect
PUB4044	The unit number in the registration address is incorrect
PUB4045	The building number in the registration address is incorrect
PUB4046	The payer type is incorrect, there is a mismatch between Person and Business type
PUB4047	The recipient type is incorrect, there is a mismatch between Person and Business type
PUB4048	The payment instrument category is missing or incorrect
PUB4049	The payment instrument recipient ID is missing
PUB4050	The payment instrument currency is missing
PUB4051	The payment instrument currency is incorrect
PUB4052	The payment instrument country is incorrect
PUB4053	The payment instrument mobile number is missing
PUB4054	The payment instrument mobile number is incorrect
PUB4055	The payment instrument bank country is incorrect
PUB4056	The payment instrument token is missing
PUB4057	The payment instrument recipient ID is incorrect
PUB4058	The payment instrument bank account type is incorrect
PUB4059	The person's email is duplicated
PUB4060	The person's email is incorrect
PUB4095	The business payer's email is incorrect
PUB4061	The business recipient's email is incorrect
PUB4062	The person's email is incorrect
PUB4063	The payer must be at least 18 years old. Please check the date of birth
PUB4064	The recipient must be at least 18 years old. Please check the date of birth
PUB4065	The instrument category ID conflicts with the existing payment instrument: only one of recipient_instrument_id or payment_instrument_category should be provided
PUB4066	The payment type conflicts with the one defined by the payer and recipient: only one of source_account_id or recipient_instrument_id should be provided when payment_type is present
PUB4067	The source currency conflicts with a part of the source amount object: only one of source_currency or source_amount object should be provided
PUB4068	The source account object currency conflicts with the one associated with source_account_id: only one of source_account_id or source_currency should be provided
PUB4069	The recipient instrument ID is incorrect
PUB4070	The source account ID is missing
PUB4071	The source account ID is incorrect
PUB4072	The source currency is missing
PUB4073	The source currency is incorrect
PUB4074	The source amount is missing
PUB4075	The source amount is incorrect
PUB4076	The source currency is incorrect
PUB4077	The target currency is missing
PUB4078	The target currency is incorrect
PUB4079	The target amount is missing
PUB4080	The target amount is incorrect
PUB4081	The target currency is incorrect
PUB4082	The destination country is missing
PUB4083	The destination country is incorrect
PUB4084	The payment instrument category is missing
PUB4085	The payment instrument category is incorrect
PUB4086	The payment type is missing
PUB4087	The payment type is incorrect
PUB4088	The source account is not found
PUB4089	The payment instrument is not found
PUB4090	The payment program is not found
PUB4091	The source account currency does not match the one in the request: source_account_id was provided together with source_amount but the source_amount currency is different from the one of the source account
PUB4092	The target currency [%s] does not match the recipient instrument currency [%s]
PUB4093	The source currency cannot be found in the request
PUB4094	The target currency cannot be found in the request
PUB4096	The recipient ID is incorrect
PUB4097	The payment instrument ID is incorrect
PUB4098	The source account ID is missing
PUB4099	The source account ID is incorrect
PUB4100	The currency is missing
PUB4101	The currency is incorrect
PUB4102	The amount is missing
PUB4103	The amount is incorrect
PUB4104	The operation type is missing
PUB4105	The operation type is incorrect
PUB4106	The currency of the target_amount object is missing
PUB4107	The currency of the target_amount object is incorrect
PUB4108	The amount of the target_amount object is missing
PUB4109	The amount of the target_amount object is incorrect
PUB4110	The target currency of the operation object is incorrect
PUB4111	The currency of the source_amount object is missing
PUB4112	The currency of the source_amount object is incorrect
PUB4113	The amount of the source_amount object is missing
PUB4114	The amount of the source_amount object is incorrect
PUB4115	The source currency of the operation object is incorrect
PUB4116	The exchange rate ID is incorrect
PUB4117	The KYT object is missing
PUB4118	The destination country is missing
PUB4119	The destination country is incorrect
PUB4120	The payment purpose is missing
PUB4121	The payment purpose is incorrect
PUB4122	The commercial activity is missing
PUB4123	The payment description is missing
PUB4124	The beneficiary bank account type is incorrect
PUB4125	The source of funds is incorrect
PUB4126	The relationship with the sender is incorrect
PUB4127	The recipient and recipient_id can't be provided at the same time
PUB4128	The amount and exchange_rate_id can't be provided at the same time
PUB4129	The amount and operation object can't be provided at the same time
PUB4130	The exchange_rate_id and operation can't be provided at the same time
PUB4131	The amount, exchange_rate_id, or operation is required
PUB4132	The payment instrument ID is required when exchange_rate_id is provided
PUB4133	For a FORWARD payment, the source amount is required
PUB4134	For a FORWARD payment, the target currency is required
PUB4135	For a REVERSE payment, the target amount is required
PUB4136	For a REVERSE payment, the source currency is required
PUB4137	The payment instrument or its ID is required
PUB4138	The recipient information or recipient_id is required
PUB4139	The payment instrument ID conflicts with the data provided. If you provide the payment_instrument_id, there is no need to provide the recipient, recipient_id, or payment instrument
PUB4140	The source account was not found
PUB4141	The payment program was not found
PUB4142	The exchange rate was not found
PUB4143	The exchange rate has not been confirmed
PUB4144	The exchange rate has been canceled, please request a new rate and try again
PUB4145	Duplicate reference
PUB4146	The payer date of birth cannot be in the future. Please check the date of birth
PUB4147	The recipient date of birth cannot be in the future. Please check the date of birth
PUB4219	The payer's identity document expiry date cannot be in the past. Please check the expiry date
PUB4220	The recipient's identity document expiry date cannot be in the past. Please check the expiry date
PUB4221	The payer's identity document issue date cannot be in the future. Please check the issue date
PUB4222	The recipient's identity document issue date cannot be in the future. Please check the issue date
PUB5001	General internal error. See error message for details.
PUB5002	The operation not allowed for this account
PUB5003	The operation not allowed for this entity type
PUB5011	The operation allowed for expired exchange rates only
PUB5012	The exchange rate is incorrect
PUB5013	The exchange rate state is incorrect for the operation
PUB5014	The exchange rate has been expired, please request a new rate and try again
PUB5021	The payer was not found
PUB5022	The recipient was not found
PUB5031	The operation is not allowed for this payment state
PUB5041	The payment instrument ID is incorrect
PUB5045	Validation error
PUB5046	Payment instrument validation error
PUB5047	Exchange rate validation error
PUB5048	The amount is lower than the defined payer limit
PUB5049	The amount is lower than the limit allowed for the selected payment method
PUB5050	The amount is greater than the limit allowed for the selected payment method
PUB5051	The amount exceeds the payer's maximum allowed for 30 calendar days by %s %s
PUB5052	The amount is lower than the defined recipient limit
PUB5053	The amount exceeds the recipient maximum allowed for 30 calendar days by %s %s
PUB5054	Single payment validation error
PUB5055	Insufficient funds in the source account
PUB9001	External system error.

Our mission is to always provide backwards compatible APIs. We commit not to deploy breaking changes within major versions unless such change is mandatory in order to fix critical security or compliance issue.

However, please note that as with every product this API is evolving. New endpoints will be published and new parameters added. Therefore, when integrating with our APIs you should always be ready to accept new fields in responses that may not be documented yet.

• 07-07-2026:
  • Changed identity_document.issue_date from a date-time to a date (YYYY-MM-DD) on payer and recipient payloads.
• 06-07-2026:
  • Changed identity_document.expiry_date from a date-time to a date (YYYY-MM-DD) on payer and recipient payloads.
• 02-07-2026:
  • Added identity_document to the PersonPayer schema (/v2/payers), exposing structured identity document details (type, number, country issuing, issue/expiry dates, etc.) on both the create request and the GET response.
  • Deprecated government_id on PersonPayer in favour of identity_document. government_id is still accepted; when identity_document is omitted it is used as the identity document number.
• 10-05-2024:
  • Added payer management endpoints: /v2/payers (POST, PATCH). The POST endpoint now returns the created payer entity.
  • Added account_details to the BusinessPayer entity.
• 18-09-2034 Added a new endpoint to refresh exchange rates by ID: /v2/exchange-rates/{id} (PATCH). This allows updating the exchange_rate_id for a payment.
• 14-09-2023 Added GET new exchange rate based on existing expired rate.
• 24-08-2023 Added POST payment documents upload endpoint and extend PATCH payment to support the documents flow.
• 05-05-2023 Moved Discovery service docs to separate section
• 25-04-2023 Added Exchange rates push event
• 24-04-2023 Added Compliance API
• 29-03-2023 Added Events API
• 20-03-2023 Added Discovery service endpoint
• 01-12-2022 Version 2.0 published

For any questions or issues, please contact us through our customer support portal or email us at support@payallps.com.