Read payout capabilities for one recipient

What a payout to this recipient would be allowed to do: one option per bank rail of the user’s that could reach them, each carrying its limits, fees, memo and purpose-code rules, and the blockers that stand in the way. Reads the provider’s live channel catalogue where one exists (Due), falling back to our declarations otherwise. Takes either a saved contactId or raw account requisites; books, quotes and writes nothing.

POST /api/v1/balance/payout/recipient/capabilities

Read payout capabilities for one recipient

cURL

curl --request POST \
  --url https://api.example.com/api/v1/balance/payout/recipient/capabilities \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{}'

200

{
  "recipient": {
    "contactId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "name": "<string>",
    "method": "<string>",
    "currency": "<string>",
    "country": "<string>",
    "bankCountry": "<string>",
    "maskedAccount": "<string>",
    "holderType": "<string>",
    "relationship": "employee",
    "firstParty": false
  },
  "available": true,
  "options": [
    {
      "provider": "swipelux",
      "bankRail": "<string>",
      "method": "<string>",
      "methodName": "<string>",
      "currency": "<string>",
      "available": true,
      "minAmount": 123,
      "bankAccountId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "providerRail": "<string>",
      "maxAmount": 123,
      "fixedFee": 123,
      "feeBps": 0,
      "estimatedRecipientAmount": 123,
      "amountToSupported": false,
      "sourceTokens": [
        "USDC"
      ],
      "memo": {
        "supported": false,
        "required": false,
        "minLength": 123,
        "maxLength": 123,
        "requiredContent": [
          "<string>"
        ]
      },
      "purpose": {
        "supported": false,
        "required": false,
        "defaultCode": "<string>",
        "codes": [
          "<string>"
        ]
      },
      "documents": {
        "supported": false,
        "required": false
      },
      "blockers": [
        {
          "code": "recipient_details_missing",
          "message": "<string>",
          "fields": [
            "<string>"
          ]
        }
      ],
      "live": false
    }
  ],
  "blockers": [
    {
      "code": "recipient_details_missing",
      "message": "<string>",
      "fields": [
        "<string>"
      ]
    }
  ]
}

Authorizations

Authorization · string · header · required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Headers

x-api-key · string | null

Body

application/json

Ask what a payout to one recipient would be allowed to do.

Either end of the client's flow answers the same question, so the request takes either: contactId for a recipient already saved, account for the form that has not been submitted yet. amount is optional and only has the rail limits checked against it — nothing is quoted or booked.

contactId · string<uuid> | null

account · SepaAccountInput · object

SEPA bank contact input.

SepaAccountInput

SwiftAccountInput

AchAccountInput

UaeAccountInput

UkFpsAccountInput

PixAccountInput

Show child attributes

address · UserAddress · object | null

Address schema for user.

Canonical field names: street_address, address_line_2, city, state, country, zip. Accepts legacy Align/IBAN field names (street_line_1, street_line_2, postal_code) for backward compatibility with existing JSONB data.

Show child attributes

relationship · enum<string> | null

How a payout contact relates to the user.

The vocabulary mirrors Swipelux's recipient relationships so the common values project onto their API unchanged, but this is our own domain type: SELF marks a first-party payout to the user's own account at another bank and has no Swipelux counterpart. Providers own that projection — see SwipeluxRecipients._recipient_relationship — so nothing here depends on a provider, and no provider enum has to carry a value it cannot accept.

Available options: employee, contractor, vendor, subsidiary, merchant, customer, landlord, family, other, self

amount · number string

Required range: x > 0

Response

200

application/json

Successful Response

Everything one recipient can be paid with, and what stands in the way.

recipient · RecipientSummary · object · required

Who is being paid, as the capabilities were resolved against them.

Show child attributes

available · boolean · required

options · RecipientPayoutOption · object[]

Show child attributes

blockers · RecipientBlocker · object[]

Show child attributes