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
Create consumers
Individuals (INDIVIDUAL) or companies (COMPANY) represented in the system.
Open sub-accounts
Dedicated accounts in a chosen currency with their own banking details, such as an IBAN.
Monitor top-ups
One query returns incoming funds across all sub-accounts in a given time window.
Make transfers
Internal (peer) and bank transfers, each confirmed with a 2FA code.
Integration flow
-
01
Access
API Key → Bearer token. Secret Key → 2FA codes.
-
02
Consumer and account
POST /consumer, then POST /consumer/{id}/account (asynchronous).
-
03
Top-ups
GET /topUp with a date filter, one query for all sub-accounts.
-
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.
/api/v1/authenticateExample request
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
{
"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.
/api/v1/consumer2.1 INDIVIDUAL type
Example request
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
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
{
"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.
/api/v1/consumer/{consumerId}/accountExample request
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
{
"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.
/api/v1/consumer/{consumerId}/accountExample request
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}'const options = { where: { id: 1002 } };
const encodedOptions = encodeURIComponent(JSON.stringify(options));Example response
[
{
"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. |
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
/api/v1/tasks/{taskId}Example request
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
{
"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.
/api/v1/topUpExample request
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:
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.
/api/v1/peerTransfer/beneficiaryExample request
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
const options = { where: { beneficaryAccountName: 'main_account_name' } };
const encodedOptions = encodeURIComponent(JSON.stringify(options));Example response
{
"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)
/api/v1/peerTransfer/beneficiaryExample request
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
{
"success": true,
"beneficiaryId": 1
}8. Initiating a Peer Transfer
/api/v1/peerTransferExample request
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
{
"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.
/api/v1/transaction/{transactionId}/codeExample request
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
{
"success": true,
"expiresAtTimestamp": 1732261142,
"randomString": "f47ac10b58cc4372a5670e02b2c3d479"
}To generate the confirmation code on your side:
- Use a Secret Key that can be found in the
Customer's Settingstab (Admin) ⇾APIsection in the panel. It is a randomly generated string (base64) and must be securely stored. - Use the provided
randomString,transactionId, andexpiresAtvalues. - Compute the HMAC-SHA-256 digest using the shared secret key
Node.js example
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
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
/api/v1/transaction/{transactionId}/confirmExample request
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
{
"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:
{
"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.
/api/v1/bankTransfer/beneficiary12. Creating a Bank Transfer Beneficiary (if not yet created)
/api/v1/bankTransfer/beneficiaryExample request
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. |
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
{
"success": true,
"beneficiaryId": 123
}13. Initiating a Bank Transfer
/api/v1/bankTransferExample request
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
{
"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.