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.

Collect payment cards without the card number ever touching your systems. Payall shows the card form in an iframe, encrypts the card and gives your page a token.

All sensitive operations related to collecting, transmitting and storing card data are managed by Payall, so your PCI exposure is minimal. We still encourage you to get familiar with PCI DSS and fill in the PCI Self Assessment Questionnaire A when working with cards and using our Vault.

1. Your page loads the Payall script and shows the card form, an iframe served by Payall.
2. The customer enters the card. The iframe encrypts it with your public key.
3. The iframe sends the encrypted card to Payall, which tokenizes it.
4. Your page receives the token in a PanTokenized event and sends it to your server.
5. Your server stores the token and uses it for payments through the Payall API.

Your page never sees the card number: it cannot read the iframe, and the iframe only gives it the token, a masked number and the card brand.

Load the script, add an element for the form and initialize it with your client ID:

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

<div id="card-form"></div>

<script>
    const vault = PayallVault.init({
        clientId: 'your-client-id',
        container: '#card-form',
    });

    vault.addEventHandler('PanTokenized', function (event) {
        // Send the token to your server and store it there.
        console.log(event.message.token, event.message.masked_pan, event.message.brand);
    });
    vault.addEventHandler('Error', function (event) {
        console.error(event.message.code, event.message.message);
    });
    vault.addEventHandler('Cancel', function () {
        vault.destroy();
    });
</script>

Environments

The examples on this page use the production script. While you integrate and test, use the sandbox script with your sandbox client ID; switch both to production when you go live.

To try the appearance, translations and layout options before you write any code, open the playground at https://static.sandbox.payall.com/vault/v2/index.html and enter your sandbox client ID. It shows the form with the options you pick and the matching PayallVault.init call.

Always load the script from Payall. Do not copy it into your own bundle: Payall ships fixes to it without any change on your side.

This page documents version 2 of the script. Version 1, at /vault/js/dist/vault-client.js on the same hosts, is deprecated: do not use it for new integrations. It keeps working unchanged, so existing integrations are not affected, but they should migrate to version 2; the change log lists the differences and how to migrate. Breaking changes ship as a new version under a new path, so the script at a given URL never changes in an incompatible way.

PayallVault.init takes one configuration object and returns the vault:

const vault = PayallVault.init({ clientId: 'your-client-id', container: '#card-form' });

init throws an error when clientId or container is missing, or when no element matches the selector.

Opening the form again

Call vault.destroy() when the form is closed. It removes the iframe and stops the event handlers. Call PayallVault.init again to show a new, empty form.

Register handlers with vault.addEventHandler(name, handler). The handler receives the event:

{
    "eventSource": "Payall",
    "event": "PanTokenized",
    "message": {
        "token": "b3b1b3b1-3b1b-3b1b-3b1b-3b1b3b1b3b1b",
        "masked_pan": "4532 **** **** 9707",
        "brand": "Visa"
    }
}

The event names are also available in PayallVault.Events.

The iframe fills the width of its container, and its height follows the form, for example when the expiry date fields appear. Set the space around the form with the padding appearance option and the height of the inputs and buttons with size. Use iframeStyle for a width, a fixed height or a border. Every key is optional:

PayallVault.init({
    clientId: 'your-client-id',
    container: '#card-form',
    iframeStyle: { width: '400px', height: '320px', border: '1px solid #D0D5DD' },
});

border accepts any CSS border value, e.g. none or 1px solid #D0D5DD. With a fixed height the iframe no longer follows the form and may scroll.

Every key is optional; keys you leave out keep the Payall look. Invalid values and unknown keys are ignored with a warning in the browser console.

PayallVault.init({
    clientId: 'your-client-id',
    container: '#card-form',
    appearance: {
        colorPrimary: '#0055FF',
        colorInputBorder: '#D0D5DD',
        inputBorderRadius: 8,
        buttonBorderRadius: 8,
        padding: 16,
        size: 'large',
        buttonLayout: 'vertical',
    },
});

Hex colors use the #RGB or #RRGGBB format. The card number and expiry inputs always use a monospace font.

Pass the texts to replace as an object. Every key is optional; missing keys keep the English text.

PayallVault.init({
    clientId: 'your-client-id',
    container: '#card-form',
    translations: {
        panLabel: 'Número de tarjeta',
        expiryLabel: 'Fecha de expiración',
        encryptLabel: 'Guardar tarjeta',
        cancelLabel: 'Cancelar',
    },
});

Translations are shown as plain text, in any script, with punctuation and symbols such as Card number (16 digits) or Pay €10.50!. Only < and >, line breaks and invisible formatting characters are removed, and each translation is cut at 100 characters. If nothing is left, the English text is used. The keys are also available in PayallVault.TranslationKeys.

Load the script once, pass the element from a ref, and destroy the form when the component unmounts:

import { useEffect, useRef } from 'react';

const SCRIPT_URL = 'https://static.payall.com/vault/v2/js/dist/vault-client.js';
let scriptLoading = null;

function loadPayallVault() {
    if (!scriptLoading) {
        scriptLoading = new Promise((resolve, reject) => {
            const script = document.createElement('script');
            script.src = SCRIPT_URL;
            script.onload = () => resolve();
            script.onerror = () => reject(new Error('Could not load the Payall Vault script'));
            document.head.appendChild(script);
        });
    }
    return scriptLoading;
}

export function CardForm({ clientId, onToken }) {
    const container = useRef(null);

    useEffect(() => {
        let vault = null;
        let unmounted = false;
        loadPayallVault().then(() => {
            if (unmounted) return;
            vault = PayallVault.init({ clientId, container: container.current });
            vault.addEventHandler('PanTokenized', event => onToken(event.message.token));
        });
        return () => {
            unmounted = true;
            if (vault) vault.destroy();
        };
    }, [clientId]);

    return <div ref={container} />;
}

Show the form in a WebView that loads a small HTML page with the same code as on a website, and forward the events to the app. The page must be loaded over HTTPS, or with an HTTPS base URL, because the card is encrypted with the Web Crypto API, which only works in secure contexts.

<!DOCTYPE html>
<html>
<head>
    <meta name="viewport" content="width=device-width, initial-scale=1">
    <script src="https://static.payall.com/vault/v2/js/dist/vault-client.js"></script>
</head>
<body style="margin: 0">
<div id="card-form"></div>
<script>
    const vault = PayallVault.init({
        clientId: 'your-client-id',
        container: '#card-form',
        appearance: { size: 'large', padding: 16, buttonLayout: 'vertical' },
    });
    ['PanTokenized', 'Error', 'Cancel'].forEach(function (name) {
        vault.addEventHandler(name, function (event) {
            const data = JSON.stringify(event);
            if (window.ReactNativeWebView) {
                window.ReactNativeWebView.postMessage(data);            // React Native
            } else if (window.webkit && window.webkit.messageHandlers.payall) {
                window.webkit.messageHandlers.payall.postMessage(data); // iOS WKWebView
            } else if (window.PayallBridge) {
                window.PayallBridge.onEvent(data);                      // Android @JavascriptInterface
            }
        });
    });
</script>
</body>
</html>

Host the page on your HTTPS domain, or load it as a string with an HTTPS base URL (loadHTMLString(_:baseURL:) on iOS, loadDataWithBaseURL on Android, source={{ html, baseUrl }} in React Native). Do not open the iframe URL directly: its parameters are internal and may change.

Type declarations are published next to the script, at https://static.payall.com/vault/v2/js/dist/vault-client.d.ts, and at the same path on sandbox. Save the file in your project and reference it to get autocompletion and type checks:

/// <reference path="./vault-client.d.ts" />

const vault = PayallVault.init({ clientId: 'your-client-id', container: '#card-form', appearance: { size: 'large' } });
vault.addEventHandler('PanTokenized', event => saveToken(event.message.token));

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <title>Add a card</title>
    <script src="https://static.payall.com/vault/v2/js/dist/vault-client.js"></script>
</head>
<body>
    <button id="add-card">Add a card</button>
    <div id="card-form"></div>
    <script>
        let vault = null;

        document.getElementById('add-card').addEventListener('click', function () {
            if (vault) vault.destroy();
            vault = PayallVault.init({
                clientId: 'your-client-id',
                container: '#card-form',
                appearance: { colorPrimary: '#0055FF', padding: 16 },
                iframeStyle: { width: '400px' },
            });
            vault.addEventHandler('PanTokenized', function (event) {
                fetch('/cards', { method: 'POST', body: JSON.stringify({ token: event.message.token }) });
                vault.destroy();
            });
            vault.addEventHandler('Error', function (event) {
                if (event.message.code === 'configuration') {
                    console.error('The card form is not configured:', event.message.message);
                }
            });
            vault.addEventHandler('Cancel', function () {
                vault.destroy();
            });
        });
    </script>
</body>
</html>

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:

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.

• 20-10-2026:
  • Added corporation, partnership, sole_proprietorship and non_incorporated_entity to the organization_legal_structure values of the BusinessPayer schema (POST /v2/payers). Any other value is rejected. The values are additive, so existing integrations are unaffected.
• 04-09-2026:
  • Added payer_id, recipient_id and quote to the StatusChangeEvent schema of the Events API (/v2/payall/payment/StatusChange/{tenant_id}). payer_id and recipient_id are the Payall identifiers of the two parties of the payment, the same ones returned when the payment was created. quote carries the exchange rate quote the payment is priced with — its id, source_amount, target_amount and expiration_date — so the event can be matched against the rate quoted before the payment was initiated. The fields are additive, so existing integrations are unaffected.
• 03-09-2026:
  • Added auto_confirmed to the PaymentResponse schema (/v2/single-payment). true when the caller holds the auto-confirm scope and the payment was confirmed automatically right after creation; false when it was instead parked at PendingConfirmation, awaiting an explicit confirm call.
  • Added POST /v2/payments/confirm, guarded by the PAYMENTS scope, to confirm a payment parked at PendingConfirmation. The payment is named by id in the request body. Rejected with a 405 for payments in any other state, and with a 404 for an ID not available to your credentials.
• 02-09-2026:
  • Added payer to the PaymentRequest schema (/v2/single-payment), allowing a payment to be initiated on behalf of a specific payer instead of the owner of the account resolved from your credentials. The payer is onboarded through the same path as POST /v2/payers, so it is provisioned with its own payment instrument and account, and an external_id that is already onboarded is rejected with PUB5056 rather than reused. The field is optional, so existing requests are unaffected.
  • Onboarding a payer this way requires the ONBOARDING scope on top of the PAYMENTS scope the endpoint already requires; without it the request is rejected with the new PUB2003 and HTTP 403.
  • payer and source_account_id are mutually exclusive, and exactly one of them is required. A payment made on behalf of a payer is funded by the account provisioned for that payer during onboarding, so no source account is named; sending both is rejected with the new PUB4235. source_account_id remains required for requests that do not name a payer.
• 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

• 21-10-2026:

  • Published version 2 of the card form script at https://static.payall.com/vault/v2/js/dist/vault-client.js, and at https://static.sandbox.payall.com/vault/v2/js/dist/vault-client.js on sandbox. The PCI Vault iframe guide documents version 2.

  • New in version 2:

    • appearance option to match the form to your site: colors, corner radius, input and button size, padding, font and button layout.
    • The iframe fills the width of its container and its height follows the form, so it no longer needs a fixed size.
    • container accepts a CSS selector or an element, e.g. a React or Vue ref.
    • vault.destroy() removes the form and its event handlers, so the form can be opened again with a new PayallVault.init call.
    • Error events carry a code: configuration, validation or tokenization.
    • New configurationError translation key. Translations may now contain digits, punctuation and symbols, e.g. Pay €10.50!, up to 100 characters.
    • Cancel clears the card details and errors before the Cancel event is sent.
    • TypeScript declarations published next to the script, at https://static.payall.com/vault/v2/js/dist/vault-client.d.ts.

  • Breaking changes compared with version 1:

    • PayallVault.init(clientId, elementId, options) is replaced by PayallVault.init(config), which takes a single configuration object.
    • container is required. There is no default payall-vault element.
    • theme is removed. Use appearance instead.
    • translations must be a plain object. A Map is no longer accepted.
    • The iframe no longer defaults to 100vw by 100vh: it takes the full width of its container and the height of the form. Set iframeStyle for a fixed size.
    • The default layout changed: inputs take the full width and the Encrypt and Cancel buttons share one row. Set appearance.buttonLayout to vertical to stack the buttons.

  • To migrate, change the script URL and the init call. Version 1:

    // <script src="https://static.payall.com/vault/js/dist/vault-client.js"></script>
    const vault = PayallVault.init('your-client-id', 'card-form', {
        translations: new Map([['encryptLabel', 'Save card']]),
        theme: 'payall',
    });
    

    Version 2:

    // <script src="https://static.payall.com/vault/v2/js/dist/vault-client.js"></script>
    const vault = PayallVault.init({
        clientId: 'your-client-id',
        container: '#card-form',
        translations: { encryptLabel: 'Save card' },
        appearance: { colorPrimary: '#0055FF' },
    });
    

    Event handlers and the events they receive are unchanged.

  • Version 1, at https://static.payall.com/vault/js/dist/vault-client.js and https://static.sandbox.payall.com/vault/js/dist/vault-client.js, is deprecated. New integrations must use version 2. Version 1 remains available and unchanged, so existing integrations keep working without any change, but they should migrate to version 2 as described above.

  • Fixes and backwards compatible additions within a major version are delivered automatically at the same URL. Breaking changes ship as a new major version under a new path, such as /v3/, while earlier versions stay available.

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