1:1 payouts (payout instructions)

A 1:1 payout (1:1 transaction) lets you specify, when registering a transaction, which of your verified bank accounts should receive funds from that specific transaction—instead of, or in addition to, the standard aggregated settlement.

Add a payout object with one or more positions to the transaction registration request body. Each position specifies the destination IBAN, transfer title (for example, an invoice number), and the net amount to be paid out.

POST/api/v1_0/payments/register→Registration with a payout object: 1:1 fund routing and checksum.Full contract in the API Reference

Must be enabled for the service

This feature is disabled by default. To use it, the 1:1 payouts option must be enabled for your service by dpay. If you send a payout object for a service without this option enabled, the registration request will be rejected.

How it works

1. Register a transaction with a payout object—for example, a payment of PLN 1,000, of which PLN 250 should be sent to account A with the title FV 2026/06/001.
2. After the transaction is paid, dpay creates a separate bank transfer to every specified IBAN, using the provided title.
3. Funds not allocated to any position—the remainder—are included in the standard aggregated settlement to the service's default account.

Rules

• Only your own verified accounts. Every IBAN must belong to one of your verified bank accounts on the allowlist. An IBAN outside the allowlist causes the registration request to be rejected.
• Two fee modes. The fee_mode field determines how amounts are interpreted and where the dpay fee is deducted—see Fee modes below.
• Positions may be partial. The total amount of all positions cannot exceed the transaction value. This hard validation is performed during registration in both fee modes (net and gross); exceeding it rejects the entire registration request. In net mode, an additional, stricter value - fee limit is enforced only during settlement. Exceeding that limit does not reject registration; the payout instruction is skipped and the transaction is settled normally. Any part not covered by positions is included in the standard aggregated settlement.
• A title is required for every position and is used as the bank transfer title—for example, an invoice number.
• payout does not affect the checksum. Calculate the checksum exactly as for a standard transaction registration request.

Fee modes (fee_mode)

The dpay fee must always be deducted from the transaction. The fee_mode field determines how this is reconciled with the position amounts.

net (default)

The position amount is the exact amount to be sent to the specified IBAN. The unallocated remainder covers the fee, so the sum of all positions cannot exceed value - fee. If it does—for example, when trying to route 100% of the transaction value—the instruction is skipped and the transaction is settled normally.

gross

The position amount is a gross share of the transaction value, and the dpay fee is deducted proportionally from every payout:

sent to IBAN = item_amount × (value - commission) / value

This lets you route 100% of the transaction—the sum of all positions may equal the transaction value. The fee is deducted by reducing each payout proportionally.

When should you use gross?

Use gross when you want to route all, or almost all, of the transaction value to the specified accounts without leaving a margin for the fee. For example, for a PLN 100 payment with a PLN 5 fee and a PLN 100 gross position, PLN 95 is sent to the IBAN and dpay collects the PLN 5 fee.

payout object structure

Field	Type	Required	Description
fee_mode	string	no	net (default) or gross—determines how the fee is deducted; see above
positions	array	yes	List of positions (at least one)
positions[].iban	string	yes	Destination IBAN; it must belong to one of the merchant's verified accounts
positions[].title	string	yes	Bank transfer title or invoice number (maximum 255 characters)
positions[].amount	number	yes	Amount for this IBAN in PLN; in net, the net payout amount; in gross, the gross share

Example: partial payout in net mode

{
  "service": "MyShop",
  "transactionType": "transfers",
  "value": 1000.00,
  "url_success": "https://myshop.example/success",
  "url_fail": "https://myshop.example/failure",
  "url_ipn": "https://myshop.example/api/ipn",
  "checksum": "…",
  "payout": {
    "fee_mode": "net",
    "positions": [
      { "iban": "PL61109010140000071219812874", "title": "Invoice 2026/06/001", "amount": 250.00 },
      { "iban": "PL27114020040000300201355387", "title": "Invoice 2026/06/002", "amount": 150.00 }
    ]
  }
}

From a PLN 1,000 payment, PLN 250 is sent to the first account with the title FV 2026/06/001, PLN 150 to the second account, and the remainder—after deducting the dpay fee—is settled normally to the service's default account.

Example: 100% payout in gross mode

{
  "service": "MyShop",
  "transactionType": "transfers",
  "value": 100.00,
  "url_success": "https://myshop.example/success",
  "url_fail": "https://myshop.example/failure",
  "url_ipn": "https://myshop.example/api/ipn",
  "checksum": "…",
  "payout": {
    "fee_mode": "gross",
    "positions": [
      { "iban": "PL61109010140000071219812874", "title": "Invoice 2026/06/010", "amount": 100.00 }
    ]
  }
}

For a PLN 100 payment with a PLN 5 fee, PLN 95 is sent to the specified IBAN (100 × 95/100), and dpay collects the PLN 5 fee. The full transaction value was routed even though a fee was deducted.

Common errors

Situation	Cause
Rejected: option disabled	The 1:1 payouts option is not enabled for the service
Rejected: IBAN outside the allowlist	The IBAN does not belong to one of the merchant's verified accounts
Rejected: invalid IBAN	Invalid IBAN format (PL followed by 26 digits, including a valid checksum)
Rejected: total too high	The sum of all position amounts exceeds the transaction value
Rejected: missing title or amount	A position has no title or has an amount less than or equal to 0