EUR payouts

Send EUR to European bank accounts over SEPA, settled from your EUR international account. Recipients are identified by IBAN + BIC.

See the Payouts overview for common fields + customer attribution, and the NGN page for the shared payout object + management endpoints.

Prerequisites

International accounts enabled on your merchant account.
An active EUR account to send from. In the individual flow this is the sender’s own virtual account (sender_account_not_provisioned if missing); in the business/treasury flow it’s your merchant international account (no_active_international_account if missing). See the error table.
A sender for compliance — sender_customer_id (preferred) or an inline sender block.
For attribution reads on the customer feed: the API key needs customer_transaction_view.

POSTSave a EUR beneficiary, then pay by reference

POST/v1/beneficiaries

A saved EUR beneficiary captures the address the receiving network needs (the inline path does not).

Path	Field	Required	Notes
Beneficiary	`bank.iban`	yes	Recipient IBAN.
Beneficiary	`bank.bic_code`	yes	8–11 char BIC/SWIFT.
Beneficiary	`address.street` / `city` / `zip_code`	yes	Receiving-network compliance.
Beneficiary	`name`	yes	Recipient name.

Request

curl https://api.swappr.me/api/v1/beneficiaries \
  -H "Authorization: Bearer sk_test_..." \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "currency": "EUR",
    "name": "Hans Müller",
    "bank": {
      "iban": "DE89370400440532013000",
      "bic_code": "COBADEFFXXX",
      "bank_name": "Commerzbank"
    },
    "address": {
      "street": "Friedrichstraße 1",
      "city": "Berlin",
      "zip_code": "10117"
    },
    "external_reference": "vendor-de-7"
  }'

POSTCreate a EUR payout

POST/v1/payouts

amount_minor is in cents (100000 = €1,000.00). Prefer the by-beneficiary path; the inline recipient is soft-deprecated for FX.

The inline path is the simpler shape — iban + bic_code + name:

Path	Field	Required	Notes
Inline	`recipient.iban`	yes	Recipient IBAN.
Inline	`recipient.bic_code`	yes	8–11 char BIC/SWIFT.
Inline	`recipient.name`	yes	Recipient name.

Sender attribution

EUR requires the sending customer to be identified — sender_customer_id (preferred) or an inline sender block; the two are complementary (inline fields win per-field, the referenced customer’s KYC backfills gaps). customer_id must match sender_customer_id if both are passed.

Response

201 Created with the payout object (currency: "EUR"). Status transitions to paid on network confirmation — listen for the payout.paid webhook.

Errors

Code	HTTP	Cause
`fx_features_not_enabled`	403	International accounts not enabled
`no_active_international_account`	403	(Business/treasury) No active merchant EUR international account
`sender_account_not_provisioned`	422	(Individual) The sending customer has no active EUR virtual account — issue one via `POST /v1/customers/{id}/virtual_accounts`
`missing_field`	400/422	Required recipient field absent (`iban`, `bic_code`, `name`)
`beneficiary_not_found`	404	`beneficiary_id` unknown / not yours / wrong env
`beneficiary_currency_mismatch`	400	`beneficiary_id` is not a EUR beneficiary
`sender_info_required`	422	No `sender_customer_id` and no complete inline `sender` block
`customer_id_mismatch`	400	`customer_id` ≠ `sender_customer_id`
`idempotency_key_conflict`	409	Same `Idempotency-Key`, different body
`provider_error`	502	Downstream rail unreachable; retry-safe with the same key

Shared management endpoints are on the NGN page.

Request — by beneficiary (preferred)

curl https://api.swappr.me/api/v1/payouts \
  -H "Authorization: Bearer sk_test_..." \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "amount_minor": "100000",
    "currency": "EUR",
    "beneficiary_id": "ben_cmo8x2p9q0...",
    "sender_customer_id": "cust_cmoji8...",
    "customer_id": "cust_cmoji8...",
    "merchant_reference": "DE-INV-55"
  }'

Request — inline recipient (soft-deprecated for FX)

curl https://api.swappr.me/api/v1/payouts \
  -H "Authorization: Bearer sk_test_..." \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "amount_minor": "100000",
    "currency": "EUR",
    "recipient": { "iban": "DE89370400440532013000", "bic_code": "COBADEFFXXX", "name": "Hans Müller" },
    "sender_customer_id": "cust_cmoji8...",
    "merchant_reference": "DE-INV-55"
  }'

Webhook events

payout.processing → payout.paid / payout.failed (+ payout.reversed). customer_id / customer_reference included when set.

USD CAD