Send Split Settlements with the V5 API

Use this workflow on a V5 site routed to an Adyen sandbox connector with test splits enabled. First create the OpenPath recipients and map them to Adyen TEST balance accounts. Authenticate with your sandbox site's OAuth bearer token and send JSON to your V5 sandbox base URL.

Authorize or charge with allocations

Send POST /Transaction/charge with your usual payment details and a top-level split_settlement. The example authorizes USD 100. Use capture: true to request a sale. Replace both sample GUIDs with your own OpenPath recipient IDs and use test payment details.

{
  "capture": false,
  "idempotency_key": "order-1001-auth",
  "credit_card": {
    "name_on_card": "Sandbox Shopper",
    "number": "4111111111111111",
    "cvv": "737",
    "expiration_month": 3,
    "expiration_year": 2030
  },
  "detail": {
    "amount": 100,
    "currency": "USD",
    "order_id": "order-1001"
  },
  "split_settlement": {
    "total": 100,
    "reference": "order-1001",
    "splits": [
      {
        "merchant_account_id": "10000000-0000-4000-8000-000000000001",
        "amount": 90,
        "category": "merchant"
      },
      {
        "merchant_account_id": "10000000-0000-4000-8000-000000000002",
        "amount": 10,
        "category": "platform_fee"
      }
    ]
  }
}

Field	Rule
`total`	Required. Positive USD amount in dollars, with up to two decimal places. It must match `detail.amount` and equal the sum of all entries.
`splits`	Required. Include 2–20 entries, with each OpenPath recipient ID appearing once.
`merchant_account_id`	Required per entry. Use the OpenPath GUID from Settings → Sub Merchants. The recipient and its connector mapping must be enabled, and the test mapping must be verified.
`amount`	Required per entry. Positive USD amount in dollars, with up to two decimal places.
`category`	Optional business label. Allowed values are `merchant`, `platform_fee`, `tax`, `shipping`, `tip`, and `other`. Labels do not change provider instructions or select which account pays fees.
`reference`, `description`	Optional at the settlement and entry levels. Use nonblank text up to 80 characters for a reference and 256 for a description.

Capture, refund, or void

Send POST /Transaction/capture with the original authorization's Adyen PSP reference as transaction_id, the full original total, and a stable key for this capture. Omit split_settlement to inherit the saved allocations. If supplied, it must match the original split. Changes to connector mappings apply to new payments.

{
  "transaction_id": "ORIGINAL_AUTHORIZATION_PSP_REFERENCE",
  "total": 100,
  "idempotency_key": "order-1001-capture"
}

After capture is confirmed, POST /Transaction/refund uses the same original authorization reference and full total, with its own refund key. The pilot allows one full capture and one full refund. Partial captures, partial refunds, incremental authorizations, and adding allocations to a previously unsplit payment are rejected. To cancel an uncaptured authorization, use Void without allocation fields.

Check status and handle retries

Give each operation its own idempotency_key of up to 120 characters. On retry, reuse the same key and request. If the allocation is invalid or a mapping is missing, disabled, or unverified, correct the issue before sending another payment. Changing an existing payment's allocations conflicts with its stored request.
Read the transaction result even after HTTP 200. A sale, capture, or refund can initially be pending while Adyen processes it. Query GET /reports/transaction with transaction_id for the operation you want to check. Read the current state in data[].transaction.result.
For a failed refund, check the processor reason and current status before attempting recovery. Adyen may acknowledge a refund and later report a funding failure. Capture approval and gross allocations are separate from final settlement and payout.