L3 · Interface Layer API

Corporate Account API

Create consumers and multi-currency sub-accounts with their own IBAN, monitor incoming top-ups and make peer and bank transfers confirmed with 2FA. Everything over REST and JSON, authorised with a Bearer token.

What you can do with the API

Integration flow

  1. 01

    Access

    API Key → Bearer token. Secret Key → 2FA codes.

  2. 02

    Consumer and account

    POST /consumer, then POST /consumer/{id}/account (asynchronous).

  3. 03

    Top-ups

    GET /topUp with a date filter, one query for all sub-accounts.

  4. 04

    Transfer and 2FA

    beneficiary → transfer → HMAC code → confirmation.

Peer transfer

From a sub-account to the merchant’s main account (internal).

Bank transfer

To an external bank account (IBAN, sort code or routing code).

Rules worth remembering

Amounts in thousandths

amount 150000 = 150 PLN or EUR, minimum 10. The same applies to balance and lockedBalance.

Uniqueness

login is unique across the system. externalId and externalReference are unique per account, and duplicates are rejected.

Field spelling

The API uses beneficaryAccountName (without the second "i"). Keep this exact spelling in requests.

Currency must match

The transfer currency must equal the currency of the source account linked to the beneficiary.

Asynchronous steps

The IBAN appears only after the account reaches COMPLETED. A transfer waits as UNAUTHORIZED until 2FA confirmation.

Keep keys secure

Store both keys securely. The Secret Key never leaves the merchant’s system.

Endpoint reference

Method Endpoint Purpose
POST /api/v1/authenticate Bearer token from the API Key
POST /api/v1/consumer New consumer (INDIVIDUAL or COMPANY)
POST /api/v1/consumer/{consumerId}/account New sub-account in a currency (asynchronous)
GET /api/v1/consumer/{consumerId}/account Consumer accounts, balances, banking details
GET /api/v1/tasks/{taskId} Status of an asynchronous task
GET /api/v1/topUp Top-ups to sub-accounts in a time window
GET POST /api/v1/peerTransfer/beneficiary Peer transfer beneficiary
POST /api/v1/peerTransfer Initiate a peer transfer
GET POST /api/v1/bankTransfer/beneficiary Bank transfer beneficiary
POST /api/v1/bankTransfer Initiate a bank transfer
POST /api/v1/transaction/{transactionId}/code Initialize 2FA
POST /api/v1/transaction/{transactionId}/confirm Confirm with the 2FA code

Integration guide

Last updated: September 2026

This document describes a sample API integration flow for creating consumers and sub-accounts, monitoring funds, and making peer and bank transfers.

Glossary

merchant
the integrating entity that sends API requests and provides consumer and transfer data.
consumer
an individual or company represented in the system.
source account
the account from which a transfer is initiated.
beneficiary
a saved transfer recipient linked to a source account.

1. API Access

First, log in to the Corporate Account panel as an Admin. Then open the Customer’s Settings tab and navigate to the API section to generate your API Key and Secret Key. Store both keys securely.

The API Key is used to obtain an authentication token by calling POST /api/v1/authenticate.

POST/api/v1/authenticate
Example request
BASH
curl -X 'POST' \
  'https://apicorporateaccount.demo.bybillon.com/api/v1/authenticate' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
  "apiKey": "asjcnasjkcjkas"
}'

Example response

JSON
{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpX...."
}

Include the returned token in the Authorization header of all subsequent API requests using the Bearer scheme:

Authorization: Bearer {token}

The Secret Key is a separate key used exclusively to generate 2FA codes. It is generated from cryptographically secure random bytes using crypto.randomBytes and encoded as Base64. It is not used to obtain authentication tokens.

2. Create a Consumer

To create a sub-account, first create a consumer representing an individual or a company. The type field determines the applicable request fields.

POST/api/v1/consumer

2.1 INDIVIDUAL type

Example request
BASH
curl -X 'POST' \
  'https://apicorporateaccount.demo.bybillon.com/api/v1/consumer' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer {token}' \
  -H 'Content-Type: application/json' \
  -d '{
    "type": "INDIVIDUAL",
    "externalId": "customer-12345",
    "login": "john.doe",
    "phoneNumber": "+48500400300",
    "email": "jan.kowalski@example.com",
    "firstName": "Jan",
    "middleName": "Piotr",
    "lastName": "Kowalski",
    "dateOfBirth": "1990-09-03",
    "countryOfBirth": "PL",
    "nationality": "PL",
    "documentType": "ID_CARD",
    "documentNumber": "CAZ251371",
    "address": {
      "street": "Aleja Jana Pawła II",
      "buildingNumber": "9",
      "flatNumber": "150",
      "city": "Warszawa",
      "postalCode": "00-293",
      "country": "PL"
    }
  }'
Request body
Field Type Required Allowed values / format Description
type string Yes INDIVIDUAL or COMPANY Consumer type. Set to INDIVIDUAL for this request.
externalId string No Any string, max. 255 characters Merchant-provided identifier. If provided, it must be unique per account; duplicates are rejected with a validation error.
login string Yes Unique across the entire system Login used in the Corporate Account panel.
phoneNumber string Yes E.164 international format, e.g. +48123456789 Consumer phone number. Must include + and the country calling code; length and structure are validated for the destination country.
email string Yes Valid email address, e.g. jan.kowalski@example.com Consumer email address; RFC 5322-like syntax (local-part@domain.tld).
firstName string Yes 2–255 characters; letters only, including Polish/Latin diacritics; no spaces, digits, or punctuation Consumer first name.
middleName string No Up to 255 characters; letters, spaces, and hyphens only, including diacritics Consumer middle name.
lastName string Yes 2–255 characters; letters, spaces, dots, apostrophes, and hyphens only, including diacritics Consumer last name, e.g. O'Brien-Smith.
dateOfBirth string Yes ISO 8601 date (YYYY-MM-DD), e.g. 1990-09-03 Consumer date of birth.
countryOfBirth string Yes Alpha-2 country code, e.g. PL, DE Consumer country of birth.
nationality string Yes Alpha-2 country code, e.g. PL, DE Consumer nationality.
documentType string Yes ID_CARD, PASSPORT, or RESIDENCE_PERMIT Consumer document type.
documentNumber string Yes 5–20 characters; letters, digits, spaces, hyphens, and slashes only Consumer document number, e.g. CAZ251371.
address object Yes Nested address object Consumer residential address.
address.street string Yes Any string, max. 255 characters Street name.
address.buildingNumber string Yes Any string, max. 255 characters Building or house number.
address.flatNumber string No Any string, max. 255 characters Flat or apartment number.
address.city string Yes Any string, max. 255 characters City name.
address.postalCode string Yes 3–10 characters: letters, digits, spaces, and hyphens, e.g. 00-293 Postal code.
address.country string Yes Alpha-2 country code, e.g. PL, DE Address country.

2.2 COMPANY type

Example request
BASH
curl -X 'POST' \
  'https://apicorporateaccount.demo.bybillon.com/api/v1/consumer' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer {token}' \
  -H 'Content-Type: application/json' \
  -d '{
    "type": "COMPANY",
    "externalId": "company-12345",
    "login": "abc-sp-zoo",
    "phoneNumber": "+48500400300",
    "email": "jan.kowalski@example.com",
    "companyName": "ABC Sp. z o.o.",
    "registrationNumber": "0000123456",
    "accountPurpose": "Dedicated client payment account.",
    "contactName": "Tom Smith",
    "address": {
      "street": "Aleja Jana Pawła II",
      "buildingNumber": "9",
      "flatNumber": "150",
      "city": "Warszawa",
      "postalCode": "00-293",
      "country": "PL"
    }
  }'
Request body
Field Type Required Allowed values / format Description
type string Yes INDIVIDUAL or COMPANY Consumer type. Set to COMPANY for this request.
externalId string No Any string, max. 255 characters Merchant-provided identifier. If provided, it must be unique per account. Duplicates are rejected with a validation error.
login string Yes Unique across the entire system Login used in the Corporate Account panel.
phoneNumber string Yes E.164 international format, e.g. +48123456789 Consumer phone number. Must include + and the country calling code; length and structure are validated for the destination country.
email string Yes Valid email address, e.g. jan.kowalski@example.com Consumer email address; RFC 5322-like syntax (local-part@domain.tld).
companyName string Yes 2–255 characters; excludes :, *, ;, ', ", !, +, ?, vertical bar, #, <, >, =, backslash, $, %, ^, {, }, [, ] Registered company name, e.g. ABC Sp. z o.o.
registrationNumber string Yes 3–30 characters; letters, digits, spaces, hyphens, and slashes Company registration or business ID number, e.g. 0000123456.
accountPurpose string Yes Up to 255 characters; any characters allowed Intended purpose of the account, e.g. Dedicated client payment account.
contactName string Yes Up to 255 characters; letters, spaces, dots, apostrophes, and hyphens, including Unicode diacritics Full name of the company contact person.
address object Yes Nested address object Company address.
address.street string Yes Any string, max. 255 characters Street name.
address.buildingNumber string Yes Any string, max. 255 characters Building or house number.
address.flatNumber string No Any string, max. 255 characters Flat or apartment number.
address.city string Yes Any string, max. 255 characters City name.
address.postalCode string Yes 3–10 characters: letters, digits, spaces, and hyphens, e.g. 00-293 Postal code.
address.country string Yes Alpha-2 country code, e.g. PL, DE Address country.

Example response

JSON
{
  "success": true,
  "consumerId": 99
}
Field Type Description
success boolean Indicates that the request was accepted.
consumerId number Consumer identifier; use it for subsequent consumer-account requests.

3. Create an Account for a Consumer

Create an account for the consumer in the specified currency. A unique prefix is automatically added to its name; Sub Account Name may become 654321-Sub Account Name.

Account creation is an asynchronous process.

POST/api/v1/consumer/{consumerId}/account

Example request

BASH
curl -X 'POST' \
  'https://apicorporateaccount.demo.bybillon.com/api/v1/consumer/99/account' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer {token}' \
  -H 'Content-Type: application/json' \
  -d '{
    "accountName": "Sub Account Name",
    "currency": "PLN"
  }'

Request body

Field Type Required Allowed values / format Description
accountName string Yes Any string, max. 248 characters Account name requested by the merchant. A unique prefix is added automatically.
currency string Yes Supported ISO 4217 currency code, e.g. PLN Account currency.

Example response

JSON
{
  "success": true,
  "accountId": 1002,
  "taskId": "6b1359ed-1c54-4ed7-802f-9bfff570f0be"
}

Status flow

Moment Task status Account data availability
Immediately after acceptance NEW Account ID and basic details are available.
After processing COMPLETED Final account details are available, including banking details such as the IBAN.

4. Retrieve an Account

Account creation can be checked by reading the consumer account details or checking the asynchronous task. The first method returns account data; the second indicates whether the creation task completed.

4.1 Retrieve Consumer Account Details

The endpoint returns all accounts for a consumer. Filter a specific account by ID using options if needed.

GET/api/v1/consumer/{consumerId}/account
Example request
BASH
curl -X 'GET' \
  'https://apicorporateaccount.demo.bybillon.com/api/v1/consumer/99/account?options=%7B%22where%22%3A%7B%22id%22%3A1002%7D%7D' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer {token}'
JAVASCRIPT
const options = { where: { id: 1002 } };
const encodedOptions = encodeURIComponent(JSON.stringify(options));
Example response
JSON
[
  {
    "id": 1002,
    "name": "654321-Sub Account Name",
    "balance": 0,
    "lockedBalance": 0,
    "currency": "PLN",
    "isActive": true,
    "bankAccounts": [
      {
        "iban": "PL40114098017252485968965464",
        "bankName": "MBANK",
        "isDefault": true
      }
    ]
  }
]
Response fields
Field Type Description
id number Account identifier.
name string Final account name, including its generated unique prefix.
balance number Available balance in thousandths of the account currency; for a PLN account, 1000 represents 1 PLN.
lockedBalance number Locked balance in the same units as balance.
currency string Account currency.
isActive boolean Account activity status.
bankAccounts[].beneficiaryName string Name of the beneficiary associated with the bank account details.
bankAccounts[].beneficiaryAddress string Address of the beneficiary associated with the bank account details.
bankAccounts[].iban string or undefined Bank account IBAN.
bankAccounts[].BIC string or undefined Bank Identifier Code.
bankAccounts[].sortCode string or undefined Bank sort code.
bankAccounts[].accountNumber string or undefined Bank account number.
bankAccounts[].routingCode string or undefined Bank routing code.
bankAccounts[].bankName string Bank name.
bankAccounts[].isDefault boolean Indicates whether this is the default bank account.
Note

The fields returned in each bankAccounts[] entry may vary depending on the account currency and the country associated with its banking details. For example, some accounts may provide an iban and BIC, while others may provide an accountNumber with a sortCode or routingCode. Do not assume that every field listed above is present in every response

4.2 Retrieve Task Details

GET/api/v1/tasks/{taskId}
Example request
BASH
curl -X 'GET' \
  'https://apicorporateaccount.demo.bybillon.com/api/v1/tasks/6b1359ed-1c54-4ed7-802f-9bfff570f0be' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer {token}'
Example response
JSON
{
  "type": "ACCOUNT_CREATE",
  "status": "COMPLETED"
}
Field Type Description
type string Task type.
status string Current task status.

5. Top-Up Monitoring

To check whether funds have been credited to sub-accounts in a recent time window, query top-up records instead of checking each sub-account individually.

GET/api/v1/topUp

Example request

BASH
curl -X 'GET' \
  'https://apicorporateaccount.demo.bybillon.com/api/v1/topUp?options=%7B%22where%22%3A%7B%22paidDate%22%3A%7B%22Op.between%22%3A%5B%222026-09-29T06%3A10%3A00.450Z%22%2C%222026-09-29T06%3A25%3A00.450Z%22%5D%7D%2C%22accountId%22%3A%7B%22Op.notIn%22%3A%5B1212%2C2212%5D%7D%7D%7D' \
  -H 'Authorization: Bearer {token}'

The following example retrieves top-ups from the last 10 minutes while excluding main EUR and PLN accounts:

JAVASCRIPT
const to = new Date().toISOString();
const from = new Date(Date.now() - 10 * 60 * 1000).toISOString();
const options = {
  where: {
    paidDate: { 'Op.between': [from, to] },
    accountId: { 'Op.notIn': [MAIN_EUR_ACCOUNT_ID, MAIN_PLN_ACCOUNT_ID] },
  },
};

const encodedOptions = encodeURIComponent(JSON.stringify(options));
// GET /api/v1/topUp?options={encodedOptions}

This detects recent incoming funds across sub-accounts without querying each account separately.

6. Peer Transfer Beneficiary Setup

To transfer funds internally from a sub-account to the main account, first define a beneficiary. Each beneficiary is linked to a particular source account. Therefore, transferring from multiple sub-accounts to the same main account requires a separate beneficiary for each sub-account.

Store the beneficiary ID against its source account, or query existing beneficiaries before creating another one.

GET/api/v1/peerTransfer/beneficiary

Example request

BASH
curl -X 'GET' \
  'https://apicorporateaccount.demo.bybillon.com/api/v1/peerTransfer/beneficiary?options=%7B%22where%22%3A%7B%22beneficaryAccountName%22%3A%22main_account_name%22%7D%7D' \
  -H 'Authorization: Bearer {token}'

Query options

JAVASCRIPT
const options = { where: { beneficaryAccountName: 'main_account_name' } };
const encodedOptions = encodeURIComponent(JSON.stringify(options));

Example response

JSON
{
  "count": 1,
  "rows": [
    {
      "id": 55,
      "accountId": 102,
      "beneficaryAccountName": "main_account_name",
      "name": "Example name",
      "currency": "EUR",
      "createdAt": "2025-06-10T13:51:28.705Z",
      "updatedAt": "2025-06-10T13:51:28.705Z"
    }
  ]
}

Here, accountId identifies the source account. If no returned row has the intended source accountId, create a beneficiary as described in section 7.

The API field is spelled beneficaryAccountName. Keep this exact spelling in requests.

7. Creating a Peer Transfer Beneficiary (if not yet created)

POST/api/v1/peerTransfer/beneficiary

Example request

BASH
curl -X 'POST' \
  'https://apicorporateaccount.demo.bybillon.com/api/v1/peerTransfer/beneficiary' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer {token}' \
  -H 'Content-Type: application/json' \
  -d '{
    "accountId": 102,
    "name": "Example name",
    "beneficaryAccountName": "main_account_name"
  }'

Request body

Field Type Required Allowed values / format Description
accountId number Yes ID of an existing source account Account from which peer transfers to this beneficiary will be initiated.
beneficaryAccountName string Yes Beneficiary account name in Corporate Account Name of the destination account in Corporate Account.
name string Yes Beneficiary name Name displayed in the panel.

Example response

JSON
{
  "success": true,
  "beneficiaryId": 1
}

8. Initiating a Peer Transfer

POST/api/v1/peerTransfer

Example request

BASH
curl -X 'POST' \
  'https://apicorporateaccount.demo.bybillon.com/api/v1/peerTransfer' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer {token}' \
  -H 'Content-Type: application/json' \
  -d '{
    "amount": 150000,
    "title": "Testing title",
    "currency": "EUR",
    "beneficiaryId": 1
  }'

Request body

Field Type Required Allowed values / format Description
amount number Yes Minimum 10 Amount in thousandths of the selected currency: 150000 represents 150 EUR for currency: "EUR".
title string Yes Max. 255 characters Transfer title.
currency string Yes Value from CurrencyCodesEnum, e.g. EUR. Must match the currency of the source account linked to the beneficiary identified by beneficiaryId Transfer currency.
beneficiaryId number Yes Numeric ID of an existing peer-transfer beneficiary Identifies the beneficiary linked to the source account.
externalReference string No Max. 255 characters Merchant reference. If supplied, it must be unique per account. A duplicate is rejected with a validation error.

Example response

JSON
{
  "success": true,
  "transactionId": "7362d756-7fb0-4052-8ed2-43dc0aa4e21e",
  "authorizationRequired": true
}

If authorizationRequired is true, the transaction has status UNAUTHORIZED and requires confirmation.

9. Initialize 2FA for Transaction Confirmation

This endpoint initializes the 2FA process for confirming a transaction. It generates a time-limited, unique confirmation code that you must use to confirm the transaction within a specified time limit (60 seconds). The confirmation code is not returned in the response. Instead, you generate it independently using the Secret Key and the provided parameters.

POST/api/v1/transaction/{transactionId}/code

Example request

BASH
curl -X 'POST' \
  'https://apicorporateaccount.demo.bybillon.com/api/v1/transaction/7362d756-7fb0-4052-8ed2-43dc0aa4e21e/code' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer {token}' \
  -d ''

Example response

JSON
{
  "success": true,
  "expiresAtTimestamp": 1732261142,
  "randomString": "f47ac10b58cc4372a5670e02b2c3d479"
}

To generate the confirmation code on your side:

  1. Use a Secret Key that can be found in the Customer's Settings tab (Admin) ⇾ API section in the panel. It is a randomly generated string (base64) and must be securely stored.
  2. Use the provided randomString, transactionId, and expiresAt values.
  3. Compute the HMAC-SHA-256 digest using the shared secret key

Node.js example

JAVASCRIPT
const crypto = require('crypto');

const payload = `${transactionId}${expiresAtTimestamp}${randomString}`;
const hmac = crypto.createHmac('sha256', Buffer.from(secretKey, 'base64'));
hmac.update(payload);
const code = parseInt(hmac.digest('hex').slice(-6), 16) % 1000000;
const formattedCode = String(code).padStart(6, '0');

Python example

PYTHON
import hmac
import hashlib
import base64

def generate_authorization_code(secret_key, transaction_id, expires_at_timestamp, random_string):
    payload = f"{transaction_id}{expires_at_timestamp}{random_string}"

    secret_key_bytes = base64.b64decode(secret_key)

    hmac_object = hmac.new(secret_key_bytes, payload.encode('utf-8'), hashlib.sha256)

    hmac_digest = hmac_object.hexdigest()
    code = int(hmac_digest[-6:], 16) % 1000000

    formatted_code = str(code).zfill(6)

    return formatted_code

secret_key = "abc"
transaction_id = "7db45587-86b0-493f-9b65-d79ab519dbf2"
expires_at_timestamp = 1736850206
random_string = "e3fd70a9ecce063b1c030ab6cbc3a41f"
code = generate_authorization_code(secret_key, transaction_id, expires_at_timestamp, random_string)
print(f"Generated 2FA code: {code}")

10. Confirm Transaction with 2FA

POST/api/v1/transaction/{transactionId}/confirm

Example request

BASH
curl -X 'POST' \
  'https://apicorporateaccount.demo.bybillon.com/api/v1/transaction/7362d756-7fb0-4052-8ed2-43dc0aa4e21e/confirm' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer {token}' \
  -H 'Content-Type: application/json' \
  -d '{
    "verificationCode": "352256"
  }'

Use the generated formattedCode as the value of verificationCode.

Example response

JSON
{
  "success": true
}

A successful confirmation accepts the code and changes the transaction status to IN_PROGRESS. If the code is invalid or expired, confirmation is rejected:

JSON
{
  "statusCode": 400,
  "message": "Invalid verification code!",
  "error": "Bad Request"
}

For each payment, follow POST /api/v1/transaction/{transactionId}/code immediately with the matching POST /api/v1/transaction/{transactionId}/confirm before starting confirmation for another payment.

11. Bank Transfer Beneficiary Setup

Before creating a bank transfer, define its beneficiary. Each beneficiary is linked to one source account. After creation, the merchant can reuse its ID for later transfers and update it if needed.

To check whether a matching beneficiary exists, use the endpoint below with appropriate query parameters, as with the peer-transfer beneficiary lookup.

GET/api/v1/bankTransfer/beneficiary

12. Creating a Bank Transfer Beneficiary (if not yet created)

POST/api/v1/bankTransfer/beneficiary

Example request

BASH
curl -X 'POST' \
  'https://apicorporateaccount.demo.bybillon.com/api/v1/bankTransfer/beneficiary' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer {token}' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "John Doe",
    "address": "5037 Diam Rd.",
    "countryCode": "PL",
    "bankName": "PKO SA",
    "iban": "PL10105000997603123456789123",
    "accountId": 1
  }'

Request body

Field Type Required Allowed values / format Description
name string Yes 5–70 characters; must not contain :, *, ;, ', ", !, +, ?, vertical bar, or # Beneficiary name.
address string Yes 3–70 characters; same excluded characters as name Beneficiary address.
countryCode string Yes Two-character value from CountryCodesEnum, e.g. PL Beneficiary country code.
bankName string No If provided and non-empty: 3–70 characters; same excluded characters as name Beneficiary bank name.
BIC string No 8 or 11 characters: four uppercase letters, two uppercase letters, two uppercase letters or digits, and optionally three uppercase letters or digits; no spaces Bank Identifier Code, e.g. ALBPPLPWXXX.
iban string No Valid IBAN starting with the prefix specified in countryCode, e.g. PL for countryCode: "PL"; whitespace is removed before validation Beneficiary IBAN.
sortCode string No Exactly six digits in XX-XX-XX format, e.g. 11-11-11 Bank sort code.
accountNumber string No Any string Beneficiary account number.
routingCode string No Exactly nine digits; permitted prefixes: 01–12, 21–32, 61–72, or 80; must pass the checksum Bank routing code, e.g. 021000021.
accountId number Yes Numeric account ID Source account linked to this beneficiary.
Note

Depending on the transfer destination and currency, some of the following bank details may be required: iban, accountNumber, BIC, sortCode and routingCode. The applicable requirements depend on the beneficiary’s countryCode and the currency of the source account associated with the beneficiary.

Example response

JSON
{
  "success": true,
  "beneficiaryId": 123
}

13. Initiating a Bank Transfer

POST/api/v1/bankTransfer

Example request

BASH
curl -X 'POST' \
  'https://apicorporateaccount.demo.bybillon.com/api/v1/bankTransfer' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer {token}' \
  -H 'Content-Type: application/json' \
  -d '{
    "amount": 150000,
    "currency": "PLN",
    "title": "Testing title",
    "externalReference": "Testing external reference",
    "beneficiaryId": 123
  }'

Request body

Field Type Required Allowed values / format Description
amount number Yes Minimum 10 Amount in thousandths of the selected currency: 150000 represents 150 PLN for currency: "PLN".
title string Yes Max. 80 characters; letters (A–Z, a–z, listed Polish characters), digits, spaces, and &, %, (, ), -, /, {, }, ., , Bank transfer title.
currency string Yes Value from CurrencyCodesEnum, e.g. PLN. Must match the currency of the source account linked to the beneficiary identified by beneficiaryId Transfer currency.
externalReference string No Max. 255 characters Merchant reference. If supplied, it must be unique per account. A duplicate is rejected with a validation error.
beneficiaryId number Yes Numeric ID of an existing bank-transfer beneficiary Identifies the beneficiary linked to the source account.

Example response

JSON
{
  "success": true,
  "transactionId": "7362d756-7fb0-4052-8ed2-43dc0aa4e21e",
  "authorizationRequired": true
}

If authorizationRequired is true, the transaction has status UNAUTHORIZED and requires the confirmation flow described in sections 9 and 10.

Building on StaBillon?

Request sandbox access and our team will walk you through the integration.