Payouts

Disburse to TR IBANs via FAST or EFT, or to cards via OCT. Query outstanding balances and run bulk payout drafts.

9 endpoints

POST/v1/payoutsOptional

Disburse to a TR IBAN (rail "fast" or "eft") or a card (rail "card", token-forwarding). Runs the payable_now gate, locks the ledger, and submits to the provider. Returns status "pending"; the terminal state arrives via the payout.* webhook. Accepts an optional Idempotency-Key header.

Request Parameters

Name	Type	Required	Description
`storeId`	string	Required	Store the payout draws from
`rail`	string	Required	"fast" \| "eft" \| "card"
`iban`	string	Required	Destination TR IBAN (validated mod-97; empty for card rail)
`holderName`	string	Required	Account holder name
`amountMinor`	integer	Required	Amount in kuruş
`currency`	string	Required	Always "TRY"
`clientReference`	string	Optional	Merchant pass-through reference

JSONRequest Example

{
  "storeId": "sto_5a6b7c8d",
  "rail": "fast",
  "iban": "TR330006100519786457841326",
  "holderName": "Acme Ltd",
  "amountMinor": 100000,
  "currency": "TRY"
}

JSONResponse Example

{
  "payoutId": "7c8d9e0f-1a2b-3c4d-5e6f-708192a3b4c5",
  "status": "pending"
}

GET/v1/payoutsOptional

List payouts with keyset pagination. Filters: storeId, status (comma-separated).

Request Parameters

Name	Type	Required	Description
`storeId`	string	Optional	Filter by store
`status`	string	Optional	Comma-separated status filter
`limit`	integer	Optional	Page size
`cursor`	string	Optional	Opaque keyset cursor

JSONResponse Example

{
  "payouts": [
    {
      "payoutId": "7c8d9e0f-1a2b-3c4d-5e6f-708192a3b4c5",
      "status": "succeeded",
      "rail": "fast",
      "amountMinor": 100000,
      "currency": "TRY",
      "createdAt": "2026-04-13T10:00:00Z",
      "resolvedAt": "2026-04-13T10:00:04Z"
    }
  ],
  "nextCursor": "eyJjcmVhdGVkQXQiOiIyMDI2LTA0LTEzVDEwOjAwOjAwWiJ9"
}

GET/v1/payouts/{id}Optional

Retrieve a payout by id.

JSONResponse Example

{
  "payoutId": "7c8d9e0f-1a2b-3c4d-5e6f-708192a3b4c5",
  "status": "succeeded",
  "merchantId": "mrc_8a1b2c3d4e5f",
  "storeId": "sto_5a6b7c8d",
  "rail": "fast",
  "iban": "TR330006100519786457841326",
  "holderName": "Acme Ltd",
  "amountMinor": 100000,
  "currency": "TRY",
  "providerRef": "fast_9a2e6b4d",
  "createdAt": "2026-04-13T10:00:00Z",
  "submittedAt": "2026-04-13T10:00:01Z",
  "resolvedAt": "2026-04-13T10:00:04Z"
}

POST/v1/payouts/{id}/cancelOptional

Cancel a payout while it is still cancellable (created / pre-lock funds_locked). Posts the reverse ledger leg when needed.

JSONRequest Example

{}

JSONResponse Example

{
  "payoutId": "7c8d9e0f-1a2b-3c4d-5e6f-708192a3b4c5",
  "status": "cancelled",
  "resolvedAt": "2026-04-13T10:00:02Z"
}

GET/v1/payouts/outstandingOptional

Aggregate sum of in-flight (not-yet-settled) payouts, used to compute payable_now.

JSONResponse Example

{
  "merchantId": "mrc_8a1b2c3d4e5f",
  "pendingMinor": 250000,
  "currency": "TRY"
}

POST/v1/payout-draftsOptional

Upload a batch of intended payouts for review. Each row is validated structurally. Approve the draft to fan each valid row out to a real payout. ≤1000 rows; one store per draft. dest = IBAN (fast/eft) or card token (card); it is never echoed back.

Request Parameters

Name	Type	Required	Description
`storeId`	string	Required	Store all rows draw from
`rows`	array	Required	[{rail, dest, holderName, amountMinor, currency}]

JSONRequest Example

{
  "storeId": "sto_5a6b7c8d",
  "rows": [
    {
      "rail": "fast",
      "dest": "TR330006100519786457841326",
      "holderName": "Acme Ltd",
      "amountMinor": 100000,
      "currency": "TRY"
    },
    {
      "rail": "eft",
      "dest": "TR120006200119000006672315",
      "holderName": "Beta AŞ",
      "amountMinor": 50000,
      "currency": "TRY"
    }
  ]
}

JSONResponse Example

{
  "draftId": "drf_8192a3b4c5d6",
  "status": "draft",
  "rowCount": 2,
  "validCount": 2,
  "invalidCount": 0,
  "createdAt": "2026-04-13T10:00:00Z"
}

GET/v1/payout-drafts/{id}Optional

Draft header plus per-row disposition.

JSONResponse Example

{
  "draftId": "drf_8192a3b4c5d6",
  "status": "draft",
  "rows": [
    {
      "rowId": "row_01",
      "rail": "fast",
      "holderName": "Acme Ltd",
      "amountMinor": 100000,
      "status": "validated"
    },
    {
      "rowId": "row_02",
      "rail": "eft",
      "holderName": "Beta AŞ",
      "amountMinor": 50000,
      "status": "validated"
    }
  ]
}

POST/v1/payout-drafts/{id}/approveOptional

Approve a draft; the in-process disburser fans each validated row out to a real payout (at most one payout per row).

JSONRequest Example

{}

JSONResponse Example

{
  "draftId": "drf_8192a3b4c5d6",
  "status": "approved"
}

POST/v1/payout-drafts/{id}/cancelOptional

Cancel a draft before it starts disbursing.

JSONRequest Example

{}

JSONResponse Example

{
  "draftId": "drf_8192a3b4c5d6",
  "status": "cancelled"
}

Category Summary

Total Endpoints

Base Domain

api.pay.kvell.group