​
Overview

A payment moves money out of one of your fiat or virtual accounts. The same endpoint handles two cases, and Balansas picks the right one from the fields you send:
  • Internal transfer — send toAccountId. Funds move between two accounts you own.
  • External payment — send payeeId. Funds move to a registered payee.
Payments are submitted to the banking provider in real time. The response returns the provider payment ID and an initial status (typically pending), which then progresses asynchronously — track it via Transactions or Webhooks.
Send either toAccountId (internal) or payeeId (external) — not both. The external payee must already exist before you reference it. See Payees.

​
Create a payment

1

Pick a source account

fromAccountId is a fiat or virtual account you own. fromAccountType (FIAT_ACCOUNT or VIRTUAL_ACCOUNT) is optional and auto-detected when omitted.
2

Choose a destination

Set toAccountId for an internal transfer, or payeeId for an external payment to a registered payee.
3

Set amount, currency, and reference

amount must be greater than 0 (max 10,000,000), currency is one of EUR, GBP, USD, and reference is a 1–200 character description.
4

Submit

POST /payments. The response includes the provider payment ID and the initial status.
curl -X POST https://stagingapi.balansas.com/functions/v1/customer-api/payments \
  -H "x-api-key: sk_test_xxxxxxxxxxxxxxxxxxxx" \
  -H "X-CSRF-Token: <64-char-hex>" \
  -H "Content-Type: application/json" \
  -d '{
    "fromAccountId": "550e8400-e29b-41d4-a716-446655440000",
    "payeeId": "990e8400-e29b-41d4-a716-446655440004",
    "amount": 1000.00,
    "currency": "EUR",
    "reference": "Invoice INV-2024-001",
    "paymentScheme": "SCT"
  }'
Plain payments (POST /payments) do not support an Idempotency-Key header. Guard against duplicate submissions on your side — for example, by disabling the submit control until the response returns and by reconciling against Transactions before retrying.

​
Fields

​
fromAccountId
string (uuid)
required
Source fiat or virtual account you own.
​
fromAccountType
string
FIAT_ACCOUNT or VIRTUAL_ACCOUNT. Auto-detected when omitted.
​
toAccountId
string (uuid)
Destination account for an internal transfer.
​
payeeId
string (uuid)
Destination payee for an external payment.
​
amount
number | string
required
Greater than 0, maximum 10,000,000.
​
currency
string
required
EUR, GBP, or USD. Must match the source account currency.
​
reference
string
required
Payment reference, 1–200 characters.
​
paymentScheme
string
Optional for external payments: SCT (EUR); FPS, CHAPS (GBP); ACH, ACH_SAME_DAY, DOMESTIC_WIRE (USD). Internal transfers and AtlasNet payees use the AtlasNet scheme automatically (instant, fee-free) — do not specify a scheme for AtlasNet payees.
​
payeeVerificationId
string
Verification ID for EUR Verification of Payee (VoP).
​
umbrellaLinkId
string (uuid)
Routes the payment through a Balansas-managed master business (PPA mode). See below.

​
PPA mode

Omit umbrellaLinkId to run a payment under your own business (direct mode, the default). Include it to route the payment through a GOAT Finance master business (PPA mode). For a PPA-mode payment, the source account and (for external payments) the payee must already exist under the same link. See PPA Mode for the full explanation of when and how to use it.
PPA-mode payment body
{
  "fromAccountId": "550e8400-e29b-41d4-a716-446655440000",
  "payeeId": "990e8400-e29b-41d4-a716-446655440004",
  "amount": 1000.00,
  "currency": "EUR",
  "reference": "Invoice INV-2024-001",
  "paymentScheme": "SCT",
  "umbrellaLinkId": "550e8400-e29b-41d4-a716-446655440099"
}

Create a payment

Full request/response contract and request playground.

Payees

Register external recipients before paying them.

Transactions

Track the status of every payment.

Webhooks

Subscribe to payment.* events for async status updates.