Skip to main content
FluxanDeveloper docs
简体中文

API reference

The 19 API endpoints, authentication and environments, request headers, data formats, pagination, compatibility, rate limits and the fields of 9 objects.

Last updated 2026-11-03 · API contract v1.0.0

Overview

The API has 19 endpoints. Fields, constraints, enums and examples are all generated from the API contract. Click an endpoint to open its detail page.

ResourceEndpointSummaryScopesIdempotency key
PaymentPOST/v1/paymentsCreate paymentpayments:writeRequired
PaymentGET/v1/paymentsList paymentspayments:read—
PaymentGET/v1/payments/{payment_id}Get paymentpayments:read—
PaymentPOST/v1/payments/{payment_id}/confirmConfirm paymentpayments:writeRequired
PaymentPOST/v1/payments/{payment_id}/cancelCancel paymentpayments:writeRequired
Checkout sessionPOST/v1/checkout/sessionsCreate hosted checkout sessionpayments:writeRequired
Checkout sessionGET/v1/checkout/sessions/{session_id}Get checkout sessionpayments:read—
RefundPOST/v1/refundsCreate refundrefunds:writeRequired
RefundGET/v1/refundsList refundsrefunds:read—
RefundGET/v1/refunds/{refund_id}Get refundrefunds:read—
Balances and balance transactionsGET/v1/balancesList balancesfinance:read—
Balances and balance transactionsGET/v1/balance-transactionsList balance transactionsfinance:read—
Settlements and payoutsGET/v1/settlementsList settlementsfinance:read—
Settlements and payoutsGET/v1/settlements/{settlement_id}Get settlementfinance:read—
Settlements and payoutsGET/v1/payouts/{payout_id}Get payoutfinance:read—
DisbursementPOST/v1/disbursementsCreate a disbursementdisbursements:writeRequired
DisbursementGET/v1/disbursementsList disbursementsdisbursements:read—
DisbursementGET/v1/disbursements/{disbursement_id}Retrieve a disbursementdisbursements:read—
EventGET/v1/events/{event_id}Get eventDepends on the event type—

Note

The API doesn't support changing your payout account, changing rates, adjusting balances or executing payouts. Do these in the merchant portal, or contact the platform.

The 3 disbursement endpoints also need the platform to enable the disbursements capability for the current environment. Without it, they return 403 capability_disabled. A disbursement pays a third-party payee from your settleable balance on your instruction. It isn't a payout, and it isn't a withdrawal (the platform has no withdrawal API). For funds rules, payee rules and handling outcomes, see Disbursements.

Caution

Use API keys only on your server. In the browser, use hosted checkout, or call the API through a proxy on your own server. The docs site doesn't offer interactive API testing.

Basic conventions

  • Use HTTPS and JSON (UTF-8). Paths include the version, /v1.
  • API address: https://api.fluxan.example. Test and live use the same address, and your API key determines the environment.
  • Every response body includes a request_id. Give it to support when you troubleshoot, or search for it in the merchant portal to find the call (API call logs (opens the merchant portal in a new tab) (Requires Owner, Admin or Developer)).
  • Requests have no merchant ID field and don't accept one: the merchant and environment are derived from the API key alone.

Authentication and environments

Send the request header Authorization: Bearer <API_KEY>. A missing, invalid, revoked or expired key returns 401 unauthenticated.

  • Test keys start with sk_test_ and can access only test objects. Live keys start with sk_live_. Retrieving a live object with a test key returns 404, and the platform doesn't reveal whether the object exists.
  • The scope each endpoint needs is shown in the header area of its endpoint page. A key without the required scope returns 403 forbidden.
ScopeEndpoints you can call
payments:readlistPayments, getPayment, getCheckoutSession; payment.* and dispute.* events in getEvent
payments:writecreatePayment, confirmPayment, cancelPayment, createCheckoutSession
refunds:readlistRefunds, getRefund; refund.* events in getEvent
refunds:writecreateRefund
finance:readlistBalances, listBalanceTransactions, listSettlements, getSettlement, getPayout; settlement.* events in getEvent
disbursements:readlistDisbursements, getDisbursement; disbursement.* events in getEvent
disbursements:writecreateDisbursement

Who can create keys, and with which scopes:

CreatorScopes they can choose
Owner, AdminAll 7
DeveloperOnly scopes within their "grantable API scopes" (by default payments:read, payments:write and refunds:read, without the disbursement scopes)
Finance, ViewerCan't create keys

The Developer role can't grant finance:read or the disbursement scopes disbursements:read and disbursements:write by default, so use a key created by an Owner or Admin. Direct card also requires the platform to enable the "direct card" capability for you, which is separate from scopes. To get a test key, open the API Key page in the merchant portal (opens the merchant portal in a new tab) (Test environment; Requires Owner, Admin or Developer).

Request headers

HeaderEndpointsRequiredDescription
AuthorizationAll 19YesBearer <API_KEY>. Use server keys on your server only
Content-TypecreatePayment, confirmPayment, createCheckoutSession, createRefund, createDisbursementYesapplication/json. cancelPayment has no request body, so it doesn't need this header
Idempotency-KeycreatePayment, confirmPayment, cancelPayment, createCheckoutSession, createRefund, createDisbursementYes1–255 characters. If it's missing, the API returns 400 (error.field is Idempotency-Key). Use one key per submission, reuse the same key when you retry after a network error, and use a new key for a new submission such as a card change. See Idempotency, retries and status checks

Data formats

  • ID: A prefix, an underscore and a random string, up to 64 characters. Store IDs as opaque, case-sensitive strings and don't parse them. Common prefixes: pay_ payment, pat_ payment attempt, auth_ authentication session, cs_ checkout session, ref_ refund, dsp_ dispute, stl_ settlement, po_ payout, dsb_ disbursement, btx_ balance transaction, ltx_ ledger transaction, evt_ event, del_ delivery, mer_ merchant, req_ request.
  • Time: ISO 8601 with a time zone, UTC by default, for example 2026-09-23T09:00:00Z. period_start and period_end are dates in the business time zone.
  • Amount: An integer in the smallest currency unit, always appearing together with currency. USD 10000 means 100.00 and JPY 10000 means 10,000. Signed amounts appear only in BalanceTransaction.amount, SettlementItem.amount and Balance.net_position.
  • Currency: An uppercase three-letter code. You can use only the currencies enabled for you. Never add amounts in different currencies.
  • metadata: Up to 20 keys. A key can be up to 40 characters, and a value is a string of up to 200 characters. Don't put sensitive data such as card numbers in it. The platform rejects requests in which it detects such data.

Pagination

  • Lists return 20 items per page by default and up to 100 (limit).
  • next_cursor is an opaque string. Don't parse it or build one yourself. When you fetch the next page, send the same filters as for the first page.
  • Results are ordered by creation time, newest first, with ties broken by unique ID in descending order, so the order is stable (balance transactions are ordered by booked_at).
  • Time ranges are half-open: created_gte is inclusive and created_lt is exclusive. For example, created_gte=2026-09-23T00:00:00Z&created_lt=2026-09-24T00:00:00Z covers exactly the whole of September 23 (UTC).
Node.js: iterate over a full day of payments
const API_BASE = 'https://api.fluxan.example';

// Iterate over every payment on 2026-09-23 (UTC): while has_more is true, continue with next_cursor and the same filters
export async function* listPaymentsOfDay() {
  const filters = {
    created_gte: '2026-09-23T00:00:00Z',
    created_lt: '2026-09-24T00:00:00Z',
    limit: '100'
  };
  let cursor;
  do {
    const query = new URLSearchParams({ ...filters, ...(cursor ? { cursor } : {}) });
    const res = await fetch(`${API_BASE}/v1/payments?${query}`, {
      headers: { Authorization: `Bearer ${process.env.FLUXAN_API_KEY}` },
      signal: AbortSignal.timeout(20_000)
    });
    if (!res.ok) throw new Error(`HTTP ${res.status}`);
    const page = await res.json();
    yield* page.data;
    cursor = page.has_more ? page.next_cursor : undefined; // Opaque string: don't parse it or build one yourself
  } while (cursor);
}

Compatibility and versions

Your client must:

  1. Ignore new fields it doesn't recognize.
  2. Never treat an unknown status as success.
  3. Tolerate unknown error codes (handle them by HTTP status), unknown event types (return 2xx and ignore them) and new next_action.type values (treat them as "not completed" and query the payment).

Versioning policy: adding fields, enum values, event types, error codes or optional parameters is a compatible change and doesn't bump /v1. Removing or renaming a field, changing semantics or adding a required parameter is a breaking change. It ships as a new version, and you get advance notice.

Rate limits and timeouts

  • 429 rate_limited: The request was not executed. Wait for Retry-After seconds, then retry with the original idempotency key. Using a different API key doesn't get around the merchant's overall limit. Disbursement creation has its own per-merchant rate limit and doesn't use up the payment or refund allowance (see disbursement rate limits). The platform doesn't publish specific rate limit values.
  • 503 temporarily_unavailable: This request was also not accepted (the platform has paused new transactions on this channel). Retry later with the original idempotency key. Treat every other 5xx as an unknown outcome; see Error codes and HTTP status.
  • Client timeouts: Set at least 20 seconds for creating and confirming payments. The platform waits synchronously for the provider for about 15 seconds. Beyond that it returns 202 processing, and you get the result later through a query or a webhook.

Objects

Payment

The main payment object, which corresponds one-to-one with a merchant business order. A Payment can have multiple attempts, but at most one normal successful charge. Besides status, it has separate outcome fields; version increases with every effective business change and is used for notification deduplication and concurrency control.

NameTypeRequiredDescription
id
stringRequired

Platform payment ID.

Example: pay_demo_001

merchant_order_no
stringRequired

Merchant order ID, case-sensitive as sent.

Example: ORDER-DEMO-001

environment
stringRequired

Environment: test is the test environment and live is the live environment. Test and live objects are isolated from each other.

  • test
  • live
  • More values may be added in the future. Don't treat a status you don't recognize as success.

Example: test

amount
integer(int64)Required

Order amount, in the smallest currency unit. It can't be changed after the first submission to the provider.

Constraints: ≥ 1

Example: 10000

currency
stringRequired

Uppercase three-letter currency code.

Constraints: Format ^[A-Z]{3}$

Example: USD

status
stringRequired

Payment status. Clients must not treat an unknown status as success.

  • created: the order has been created and no valid charge attempt has been submitted yet; new attempts are allowed within the validity period
  • processing: submitted and being processed, or the outcome isn't confirmed yet; new attempts aren't allowed
  • requires_action: the current attempt needs the payer to complete an action such as authentication. When next_action isn't null, send the payer to that URL; when it's null, the payer's action isn't in the browser (direct wallet: the payer confirms in the wallet app). New attempts aren't allowed
  • failed: the latest attempt clearly failed; this is not a terminal state, and an explicit retry is possible when the deadline, attempt limit and risk conditions are met
  • succeeded: payment confirmed as successful
  • canceled: cancellation confirmed as safe
  • expired: no unresolved attempt, and the order has expired and closed
  • created: The order has been created and no valid charge attempt has been submitted yet; new attempts are allowed within the validity period
  • processing: Submitted and being processed, or the outcome isn't confirmed yet; new attempts aren't allowed
  • requires_action: The current attempt needs the payer to complete an action such as authentication. When next_action isn't null, send the payer to that URL; when it's null, the payer's action isn't in the browser (direct wallet: the payer confirms in the wallet app). New attempts aren't allowed
  • failed: The latest attempt clearly failed; this is not a terminal state, and an explicit retry is possible when the deadline, attempt limit and risk conditions are met
  • succeeded: Payment confirmed as successful
  • canceled: Cancellation confirmed as safe
  • expired: No unresolved attempt, and the order has expired and closed
  • More values may be added in the future. Don't treat a status you don't recognize as success.

Example: requires_action

resolution_status
stringRequired

Outcome confirmation.

  • known: outcome confirmed
  • needs_query: outcome unknown; the platform is running a status query against the provider using the original identifiers
  • manual_review: past the automatic query window and handed over to manual follow-up; never marked as failed automatically
  • known: Outcome confirmed
  • needs_query: Outcome unknown; the platform is running a status query against the provider using the original identifiers
  • manual_review: Past the automatic query window and handed over to manual follow-up; never marked as failed automatically
  • More values may be added in the future. Don't treat a status you don't recognize as success.

Example: known

captured_amount
integer(int64)Required

The amount confirmed as captured; equal to amount on success.

Constraints: ≥ 0

Example: 0

refunded_amount
integer(int64)Required

The confirmed effective refunded principal: the total of successful refunds minus confirmed refund returns. It excludes refunds that are still processing and platform exception refunds.

Constraints: ≥ 0

Example: 0

refund_returned_amount
integer(int64)Required

The cumulative refund principal confirmed as returned.

Constraints: ≥ 0

Example: 0

refund_reserved_amount
integer(int64)Required

Principal reserved for refunds that are processing.

Constraints: ≥ 0

Example: 0

refund_status
stringRequired

Refund summary status, derived from refunded_amount (the effective refunded principal): none, partial, full.

  • none
  • partial
  • full
  • More values may be added in the future. Don't treat a status you don't recognize as success.

Example: none

authentication_status
stringNullableRequired

The 3DS authentication status of the current attempt, taken from the authentication session status: not_required, pending, challenge, authenticated, failed, abandoned, expired. Tolerate new values. Successful authentication (authenticated) doesn't mean the charge succeeded, so don't use it to decide the payment outcome. It's null when there is no attempt yet or the attempt hasn't entered authentication.

Example: challenge

reconciliation_status
ReconciliationStatusRequired

The progress of the platform's funds processing, for reconciliation reference only. It doesn't indicate whether the payment succeeded or when you'll be paid out.

  • pending
  • matched
  • difference
  • resolved
  • More values may be added in the future. Don't treat a status you don't recognize as success.
upstream_receipt_status
UpstreamReceiptStatusRequired

The progress of the platform's funds processing, for reconciliation reference only. It doesn't indicate whether the payment succeeded or when you'll be paid out.

  • not_received
  • partially_received
  • received
  • reversed
  • More values may be added in the future. Don't treat a status you don't recognize as success.
latest_attempt_id
stringNullableRequired

ID of the latest payment attempt; null if no attempt has been submitted yet.

Example: pat_demo_001

attempt_count
integer(int32)Required

The number of attempts started. The default maximum is 3.

Constraints: ≥ 0

Example: 1

version
integer(int64)Required

Object version, which increases with every effective business change. Compare versions to discard older events, and don't order events by status name.

Constraints: ≥ 1

Example: 2

next_action
NextActionNullableRequired

The action the payer must complete when status=requires_action; null in all other cases. It's also null for a direct wallet requires_action: the payer confirms in the wallet app, with no redirect.

type
stringRequired

The initial release of the public API exposes only redirect_to_url. Clients must tolerate types that are added in the future.

  • redirect_to_url
  • More values may be added in the future. Don't treat a status you don't recognize as success.

Example: redirect_to_url

authentication_session_id
stringRequired

Authentication session ID, linked to a specific payment attempt.

Example: auth_demo_001

url
string(uri)Required

The URL of the platform's authentication page.

Example: https://pay.fluxan.example/auth/<SHORT_LIVED_TOKEN>

expires_at
string(date-time)Required

The time the authentication access expires (10 minutes at most).

Example: 2026-09-23T09:10:00Z

failure
PaymentFailureNullableRequired

The reason when the attempt that latest_attempt_id points to has clearly failed; otherwise null.

code
stringRequired

Failure reason code.

Example: card_declined

message
stringRequired

Sanitized description.

Example: The issuer declined this transaction.

attempt_id
stringRequired

ID of the failed payment attempt.

Example: pat_demo_001

description
stringNo

Order summary.

Constraints: Max length 256

Example: Example order

customer_reference
stringNo

Merchant-side customer reference.

Constraints: Max length 128

Example: CUSTOMER-DEMO-001

metadata
objectNo

Custom key-value pairs set by the merchant: up to 20 keys. A key can be up to 40 characters, and a value is a string of up to 200 characters. Don't put sensitive data such as card numbers in it. The platform checks for such data and rejects the request.

Constraints: Up to 20 keysMax value length 200

Example: {"business_order_type":"one_time_purchase"}

card
CardSummaryNullableRequired

Masked details of the card used in the latest attempt; null when there are no card details yet.

brand
stringRequired

Card brand.

Example: visa

last4
stringRequired

Last four digits of the card number.

Constraints: Format ^[0-9]{4}$

Example: 1234

created_at
string(date-time)Required

Creation time.

Example: 2026-09-23T09:00:00Z

succeeded_at
string(date-time)NullableRequired

The time the payment was confirmed as successful; null if it hasn't succeeded.

Example: null

expires_at
string(date-time)Required

The deadline for starting a new attempt, fixed at creation (by default 30 minutes after creation; the platform can adjust it to between 5 and 120 minutes, so go by this field). Expiry only closes the entry point for new attempts. It doesn't invalidate a payment that was already submitted.

Example: 2026-09-23T09:30:00Z

  • failed is not a terminal state. While the payment is within its validity period and attempt limit and passes risk checks, a new attempt can start and eventually succeed. If a refund happens after succeeded, the payment status stays succeeded; check refund_status for the refund.
  • resolution_status=needs_query means the outcome is unknown and the platform is running a status query with the provider, using the original identifiers. manual_review means the payment is past the automatic query window and has been handed over to manual follow-up. The platform never marks it as failed automatically.
  • authentication_status is the 3DS authentication status. Successful authentication doesn't mean the charge succeeded, so don't use it to decide the payment outcome.
  • version increases with every effective business change. Use it to discard older events, and don't order events by status name.
  • reconciliation_status and upstream_receipt_status track the platform's funds processing. They're for reconciliation reference only: they don't indicate whether the payment succeeded or when you'll be paid out.
  • expires_at is the deadline for starting a new attempt (30 minutes after creation by default). Expiry only closes the entry point for new attempts. It doesn't invalidate a payment that was already submitted.
Payment status transitions
Payment status transitions
  1. The payer can retry after failed, so you can't order events or statuses by status name. Compare version instead.
  2. When a succeeded payment is refunded, the payment status doesn't change. Refunds are tracked on the refund and in the payment's refund_status.

Refund

A refund request against the original payment. A payment supports multiple partial refunds, each with its own refund ID.

NameTypeRequiredDescription
id
stringRequired

Platform refund ID.

Example: ref_demo_001

version
integer(int64)Required

Object version, which increases with every effective business change (status, failure reason, returned amount). Compare versions to discard older events, and don't order events by status name.

Constraints: ≥ 1

Example: 1

payment_id
stringRequired

Original payment ID.

Example: pay_demo_001

merchant_refund_no
stringRequired

Merchant refund ID, unique within one merchant and environment.

Example: REFUND-DEMO-001

amount
integer(int64)Required

Refund principal, in the smallest currency unit.

Constraints: ≥ 1

Example: 4000

currency
stringRequired

Refund currency, inherited from the original payment.

Constraints: Format ^[A-Z]{3}$

Example: USD

status
stringRequired

Refund status. Since 2026-11-03, refunds are always approved automatically: once accepted, a refund goes straight to processing.

  • pending_review: accepted and waiting for review; no longer entered since 2026-11-03 and kept for compatibility
  • processing: accepted and submitted to the provider, or the provider's result is being confirmed; the funds stay reserved
  • succeeded: the provider confirmed the refund succeeded; the reserved funds become a final deduction
  • failed: the refund clearly did not succeed; the reserved funds are released
  • rejected: rejected in review and not submitted to the provider; no longer entered since 2026-11-03 and only seen on historical refunds
  • canceled: canceled by an authorized person before submission to the provider; the reserved funds are released
  • returned: all or part of the funds were actually returned after a refund that had been confirmed as succeeded
  • pending_review: Accepted and waiting for review; no longer entered since 2026-11-03 and kept for compatibility
  • processing: Accepted and submitted to the provider, or the provider's result is being confirmed; the funds stay reserved
  • succeeded: The provider confirmed the refund succeeded; the reserved funds become a final deduction
  • failed: The refund clearly did not succeed; the reserved funds are released
  • rejected: Rejected in review and not submitted to the provider; no longer entered since 2026-11-03 and only seen on historical refunds
  • canceled: Canceled by an authorized person before submission to the provider; the reserved funds are released
  • returned: All or part of the funds were actually returned after a refund that had been confirmed as succeeded
  • More values may be added in the future. Don't treat a status you don't recognize as success.

Example: processing

reason
stringRequired

Refund reason.

Example: requested_by_customer

returned_amount
integer(int64)Required

The cumulative principal actually returned after the refund succeeded.

Constraints: ≥ 0

Example: 0

failure
RefundFailureNullableRequired

The reason when status is failed (or rejected, for historical refunds); otherwise null.

code
stringRequired

Failure reason code.

Example: refund_failed

message
stringRequired

Sanitized description.

Example: The provider didn't execute the refund.

metadata
objectNo

Custom key-value pairs set by the merchant: up to 20 keys. A key can be up to 40 characters, and a value is a string of up to 200 characters. Don't put sensitive data such as card numbers in it. The platform checks for such data and rejects the request.

Constraints: Up to 20 keysMax value length 200

Example: {"business_order_type":"one_time_purchase"}

created_at
string(date-time)Required

The time the request was accepted.

Example: 2026-09-23T10:00:00Z

completed_at
string(date-time)NullableRequired

The time the refund entered succeeded, failed, rejected or canceled; null if it hasn't ended yet.

Example: null

  • For reason, we recommend a reason code: requested_by_customer, duplicate, fraudulent, order_canceled or other.
  • returned means the refunded funds came back after the refund had been confirmed as succeeded. The original success is kept on record, and returned_amount is the returned principal.
  • Platform exception refunds (the platform returns a duplicate charge, or an overcharge caused by an amount mismatch, to the cardholder's original payment method) aren't returned by the API and don't count toward the payment's refunded_amount or refund_status. The platform notifies you separately with an in-app notification and an email.
Refund status transitions
Refund status transitions
  • A refund is submitted to the provider as soon as it's created, so it starts in processing. This works the same in test and live, and the platform doesn't review refunds.
  • While the outcome of a processing refund is unknown, the funds stay reserved and the platform keeps running status queries. It doesn't cancel the refund locally.
  • pending_review and rejected stay in the status enum only for compatibility. They're no longer produced as of 2026-11-03 and can appear only on older records.

Checkout session

A hosted checkout session. It's linked to the order's Payment and doesn't create a second, separate payment order.

NameTypeRequiredDescription
id
stringRequired

Checkout session ID.

Example: cs_demo_002

payment_id
stringRequired

The related Payment.

Example: pay_demo_002

status
stringRequired

Checkout session status.

  • open: payment can be submitted
  • completed: appears only after the related Payment succeeds
  • expired: new submissions are no longer allowed; this doesn't mean the related payment failed
  • open: Payment can be submitted
  • completed: Appears only after the related Payment succeeds
  • expired: New submissions are no longer allowed; this doesn't mean the related payment failed
  • More values may be added in the future. Don't treat a status you don't recognize as success.

Example: open

checkout_url
string(uri)Required

The checkout page URL. It carries a short-lived credential bound to this session only, and contains no merchant server-side key. Use it only for a full-page redirect of the payer's browser: don't write it to logs, analytics tools or error reporting, and don't share it with anyone.

Example: https://pay.fluxan.example/checkout/<SHORT_LIVED_TOKEN>

expires_at
string(date-time)Required

The time the session expires, fixed at creation. A session lasts at most 30 minutes (the platform can shorten this) and never longer than the time the order has left to be paid. During the read-only period after expiry (fixed at creation; 24 hours by default, which is also the maximum), the payer can still use the original link to view the session and the payment result (read-only, no submissions). After that, the link stops working.

Example: 2026-09-23T09:30:00Z

return_url
string(uri)Required

The merchant's return URL after the payment ends.

Example: https://merchant.example/payment/return

cancel_url
string(uri)NullableRequired

The URL the payer goes to when they click "Return to merchant". Clicking it doesn't cancel a charge that was already submitted. It's null if not provided.

Example: https://merchant.example/payment/cancel

locale
stringRequired

Checkout page language.

Example: zh-CN

created_at
string(date-time)Required

Creation time.

Example: 2026-09-23T09:00:00Z

  • checkout_url contains a checkout token. Use it only for a full-page redirect of the payer's browser. Don't write it to logs, analytics tools or error reporting, and don't share it with anyone.
  • A session lasts at most 30 minutes, and never longer than the time the order has left to be paid. After it expires, it enters a read-only period (24 hours by default, which is also the maximum). During that period the link shows the result but can't accept submissions. After that, the link stops working.
  • When the payer clicks "Return to merchant" (cancel_url), that doesn't cancel the charge.

Balance

The merchant's balance buckets for a single currency. Any given amount is in exactly one bucket. Pending recovery is a separate receivable and is never hidden as a negative number in another bucket. Amounts in different currencies must not be added together.

NameTypeRequiredDescription
currency
stringRequired

Currency.

Constraints: Format ^[A-Z]{3}$

Example: USD

pending
integer(int64)Required

Pending settlement: the net amount from payments that succeeded but haven't yet met all the conditions for funds receipt, settlement period or reconciliation; it can't be paid out.

Constraints: ≥ 0

Example: 9650

available
integer(int64)Required

Settleable: the amount that meets the release conditions and isn't reserved; the only bucket that can be used for settlement payouts and disbursements.

Constraints: ≥ 0

Example: 8650

reserve
integer(int64)Required

Reserve: the amount held back under the rules and waiting to be released.

Constraints: ≥ 0

Example: 1000

risk_hold
integer(int64)Required

Risk hold: the held amount tied to a specific risk action or dispute.

Constraints: ≥ 0

Example: 0

refund_pending
integer(int64)Required

Reserved for refunds: the amount reserved by refunds that are processing.

Constraints: ≥ 0

Example: 0

payout_pending
integer(int64)Required

Reserved for payouts: the amount reserved by an active settlement whose payout isn't confirmed as complete yet.

Constraints: ≥ 0

Example: 0

disbursement_pending
integer(int64)Required

Reserved for disbursements: the amount plus disbursement fee held by disbursements that were accepted and don't have a final outcome yet. On success it's deducted; on failure or reversal it goes back to settleable.

Constraints: ≥ 0

Example: 0

merchant_receivable
integer(int64)Required

Pending recovery: a receivable the platform holds against the merchant, created by an actual forced debit and similar cases; it isn't part of the merchant's available funds.

Constraints: ≥ 0

Example: 0

book_payable
integer(int64)Required

The merchant's book payable balance = pending + available + reserve + risk_hold + refund_pending + payout_pending + disbursement_pending.

Constraints: ≥ 0

Example: 19300

net_position
integer(int64)Required

The merchant's net position (for display only) = book_payable - merchant_receivable. It can be negative and can't replace available.

Example: 19300

Balance bucketNameMeaningUsable for payouts and disbursements
pendingPending settlementMerchant net amount from payments that succeeded but haven't yet met all the conditions for funds receipt, settlement period or reconciliationNo
availableSettleableMeets the release conditions and isn't reservedYes
reserveReserveHeld back under the rules, waiting to be releasedNo
risk_holdRisk holdA hold tied to a specific risk action or disputeNo
refund_pendingReserved for refundsReserved for refunds that are processingNo
payout_pendingReserved for payoutsReserved by an active settlement, payout not yet confirmedNo
disbursement_pendingReserved for disbursementsAmount plus fee held for disbursements that were accepted but haven't succeeded or failed yetNo
merchant_receivablePending recoveryAmount you owe the platform (listed separately, not a negative balance)Not part of available funds

book_payable is the sum of the first 7 buckets. net_position = book_payable − merchant_receivable. It's for display only and can be negative.

Warning

Only available can be used for payouts and disbursements. Never add balances in different currencies to get a "total balance".

Balance transaction

A single increase or decrease in one balance bucket. A posted balance transaction can't be modified; corrections are made with a reversal and a new balance transaction.

NameTypeRequiredDescription
id
stringRequired

Balance transaction ID.

Example: btx_demo_001

type
stringRequired

Posting type, for example payment_captured (payment captured), refund_reserved (reserved for refunds), settlement_reserved (reserved for settlement), funds_released (funds released) or disbursement_reserved (reserved for disbursements). Tolerate new values.

Example: payment_captured

source_type
stringRequired

Source business object type, for example payment, refund, dispute, settlement, payout, payout_return (payout return), disbursement or adjustment.

Example: payment

source_id
stringRequired

Source business object ID.

Example: pay_demo_001

bucket
stringRequired

Balance bucket: pending, available, reserve, risk_hold, refund_pending, payout_pending, disbursement_pending (reserved for disbursements), merchant_receivable.

  • pending
  • available
  • reserve
  • risk_hold
  • refund_pending
  • payout_pending
  • disbursement_pending
  • merchant_receivable
  • More values may be added in the future. Don't treat a status you don't recognize as success.

Example: available

amount
integer(int64)Required

Signed amount, in the smallest currency unit: a positive value increases the balance bucket and a negative value decreases it.

Example: 9650

currency
stringRequired

Currency.

Constraints: Format ^[A-Z]{3}$

Example: USD

occurred_at
string(date-time)Required

The time the business event occurred.

Example: 2026-09-23T09:05:00Z

booked_at
string(date-time)Required

Posting time. A late-arriving fact is never made to look as if it arrived on time.

Example: 2026-09-23T09:05:01Z

ledger_transaction_id
stringRequired

The related ledger transaction ID. The two balance transactions of a transfer between buckets share the same ID.

Example: ltx_demo_001

  • amount is signed: a positive value increases the balance bucket and a negative value decreases it. A transfer between buckets is two balance transactions under the same ledger_transaction_id, one decrease and one increase.
  • Each balance transaction carries both the time the event occurred (occurred_at) and the time it was posted (booked_at). created_gte and created_lt apply to booked_at, so a late-arriving fact appears at the time it was actually posted, and history isn't rewritten.
  • type is the posting type, for example payment_captured (a successful payment is posted), refund_reserved (funds reserved for a refund), settlement_reserved (funds reserved for a settlement) and funds_released (funds released). Tolerate new values.
  • For disbursement entries, source_type is disbursement and source_id is the disbursement ID (dsb_…). The posting types are disbursement_reserved (reserved for a disbursement), disbursement_succeeded (disbursement succeeded, including any shortfall returned), reservation_released (reservation released after a failed disbursement) and disbursement_reversed (disbursement reversal). See disbursement funds rules.

Settlement

The settlement and its source line items.

NameTypeRequiredDescription
id
stringRequired

Settlement ID.

Example: stl_demo_001

currency
stringRequired

Settlement currency.

Constraints: Format ^[A-Z]{3}$

Example: USD

period_start
string(date)Required

The business date on which the settlement period starts (inclusive), in the merchant's settlement business time zone.

Example: 2026-09-21

period_end
string(date)Required

The business date on which the settlement period ends (inclusive).

Example: 2026-09-21

status
stringRequired

Settlement status.

  • pending_review: generated by the system and waiting for the platform to confirm the payout; the selected merchant balance has been reserved atomically
  • approved: the platform confirmed the payout, pending execution
  • rejected: rejected by the platform; the reserved funds are released
  • paying: handed over for execution, or the payout outcome isn't determined yet; the funds stay reserved
  • paid: the platform confirmed the payout as successful
  • failed: the payout clearly didn't succeed this time; the reserved funds are released
  • canceled: not sent out yet and canceled by an authorized user; the reserved funds are released
  • returned: the bank returned the payout after it had succeeded
  • pending_review: Generated by the system and waiting for the platform to confirm the payout; the selected merchant balance has been reserved atomically
  • approved: The platform confirmed the payout, pending execution
  • rejected: Rejected by the platform; the reserved funds are released
  • paying: Handed over for execution, or the payout outcome isn't determined yet; the funds stay reserved
  • paid: Payout confirmed as successful by the platform
  • failed: The payout clearly didn't succeed this time; the reserved funds are released
  • canceled: Not sent out yet and canceled by an authorized user; the reserved funds are released
  • returned: The bank returned the payout after it had succeeded
  • More values may be added in the future. Don't treat a status you don't recognize as success.

Example: paid

reserved_amount
integer(int64)Required

S, the balance this settlement reserves by moving it from available to payout_pending.

Constraints: ≥ 0

Example: 8650

fee_amount
integer(int64)Required

Settlement fee F. The default is 0.

Constraints: ≥ 0

Example: 0

payout_amount
integer(int64)Required

Actual bank payout amount = S - F.

Constraints: ≥ 0

Example: 8650

payout_account
PayoutAccountRequired

A masked snapshot of the payout account, taken when the settlement was generated.

holder_name
stringRequired

Account holder.

Example: Demo Merchant Ltd

bank_name
stringRequired

Bank name.

Example: Example Bank

account_last4
stringRequired

Last four digits of the account number.

Constraints: Format ^[0-9A-Za-z]{4}$

Example: 6789

payout_id
stringNullableRequired

The corresponding payout record; null until it has been executed.

Example: po_demo_001

created_at
string(date-time)Required

The time the settlement was generated.

Example: 2026-09-22T02:00:00Z

items
array<SettlementItem>Required
source_type
stringRequired

Source type, for example payment (net payment amount), refund_return (refund return), adjustment (manual adjustment) or disbursement_return (funds returned from a failed or reversed disbursement, or from an underpayment); tolerate new values.

Example: payment

source_id
stringRequired

Source object ID.

Example: pay_demo_001

amount
integer(int64)Required

The signed amount counted toward this settlement, in the same currency as the settlement.

Example: 8650

  • payout_amount = reserved_amount - fee_amount.
  • payout_account is a masked snapshot taken when the settlement is generated. Changing your payout account later doesn't affect existing settlements.
  • Refunds, chargebacks and reserve releases don't rewrite past settlements.

Payout

The outgoing payout record for one settlement, linked to the settlement and to a unique reference number.

NameTypeRequiredDescription
id
stringRequired

Payout ID.

Example: po_demo_001

settlement_id
stringRequired

The corresponding settlement.

Example: stl_demo_001

amount
integer(int64)Required

Payout amount, in the smallest currency unit.

Constraints: ≥ 1

Example: 8650

currency
stringRequired

Currency.

Constraints: Format ^[A-Z]{3}$

Example: USD

status
stringRequired

Payout status: created, processing, unknown, succeeded, failed, canceled, returned. When unknown, the related settlement stays paying and the funds aren't released automatically.

  • created
  • processing
  • unknown
  • succeeded
  • failed
  • canceled
  • returned
  • More values may be added in the future. Don't treat a status you don't recognize as success.

Example: succeeded

reference
stringRequired

Unique payout reference assigned by the platform; it's never reused for a new transfer.

Example: PAYOUT-REF-DEMO-001

executed_at
string(date-time)NullableRequired

The time the payout was executed; null if it hasn't been executed yet.

Example: 2026-09-22T03:00:00Z

completed_at
string(date-time)NullableRequired

The time the platform confirmed the payout as succeeded or failed; null if it hasn't been confirmed yet.

Example: 2026-09-22T05:00:00Z

  • The API can retrieve a payout only by ID (getPayout). Take the payout ID from the settlement's payout_id. There's no endpoint for listing payouts. View the list in the merchant portal.
  • unknown means the bank's result can't be confirmed for now: the settlement stays paying, the funds aren't released, and the platform runs a status query first. It never pays out twice.

Disbursement

Disbursement: pays a third-party payee from your settleable balance on your instruction. A disbursement isn't a settlement payout or a withdrawal. At acceptance, the amount plus fee are held. Acceptance only means the platform has taken on the disbursement; whether the money was paid shows in status or in a disbursement.* event whose signature you've verified. version increases with every effective change.

NameTypeRequiredDescription
id
stringRequired

Disbursement ID (dsb_).

Example: dsb_demo_001

version
integer(int64)Required

Object version, which increases with every effective change. Compare it when you process events, and don't order events by status name.

Constraints: ≥ 1

Example: 1

merchant_disbursement_no
stringRequired

Merchant disbursement ID, unique within one merchant and environment and case-sensitive. When a disbursement created in the merchant portal didn't set one, it equals the disbursement ID.

Example: DSB-DEMO-001

environment
stringRequired

Environment: test is the test environment and live is the live environment. Test and live objects are isolated from each other.

  • test
  • live
  • More values may be added in the future. Don't treat a status you don't recognize as success.

Example: test

amount
integer(int64)Required

Disbursement amount, in the smallest currency unit.

Constraints: ≥ 1

Example: 30000

currency
stringRequired

Uppercase three-letter currency code.

Constraints: Format ^[A-Z]{3}$

Example: PKR

fee
integer(int64)Required

Disbursement fee, in the smallest currency unit. It's calculated and held at acceptance with the rate version in effect then; later rate changes don't affect it.

Constraints: ≥ 0

Example: 600

method
stringRequired

Receiving method.

  • easypaisa: EasyPaisa wallet
  • jazzcash: JazzCash wallet
  • bank: bank account
  • easypaisa: EasyPaisa wallet
  • jazzcash: JazzCash wallet
  • bank: Bank account
  • More values may be added in the future. Don't treat a status you don't recognize as success.

Example: easypaisa

payee
DisbursementPayeeRequired

Payee. The full payee account appears only in the create request; responses, events, the merchant portal and exports return only the last 4 digits.

account_last4
stringRequired

Last 4 digits of the payee account.

Example: 4567

name
stringRequired

Payee name, as sent in the request.

Example: Test Payee

bank_code
DisbursementBankCodeNullableRequired

Bank code; null when the receiving method isn't bank.

  • HBL
  • UBL
  • MCB
  • MCB_ARIF_HABIB
  • NBP
  • ALFALAH
  • ALLIED
  • ASKARI
  • FAYSAL
  • MEEZAN
  • AL_HABIB
  • HABIB_METRO
  • BANK_ISLAMI
  • DUBAI_ISLAMIC
  • PUNJAB_BANK
  • SINDH_BANK
  • SONERI
  • SUMMIT
  • SILK
  • SAMBA
  • JS
  • NIB
  • APNA
  • CITI
  • NRSP
  • CDNS
  • VCB
  • VIB
  • MB
  • VIETINBANK
  • HDBANK
  • NCB
  • MSB
  • VIETABANK
  • GPBANK
  • OCEANBANK
  • NASB
  • DAB
  • ABBANK
  • BIDV
  • SHB
  • BVB
  • LPB
  • TPBANK
  • AGRIBANK
  • SCB
  • KLB
  • SEABANK
  • VRB
  • VID
  • NAMABANK
  • PVC
  • SAIGONBANK
  • TECHCOMBANK
  • EXIMBANK
  • ACB
  • VPBANK
  • OCB
  • PGBANK
  • UOB
  • IVB
  • WOORIBANK
  • SHBVN
  • VIETBANK
  • VIETCAPITALBANK
  • HONGLEONG
  • SCVN
  • IBK_HN
  • IBK_HCM
  • COOPBANK
  • CIMB
  • KBHN
  • KBHCM
  • TIMO
  • KEBHCM
  • CAKE
  • KEBHN
  • More values may be added in the future. Don't treat a status you don't recognize as success.
bank_name
stringNullableRequired

Name of the payee's bank, as returned by the disbursement channel; may be null.

Example: null

utr
stringNullableRequired

Reference number from the payee's wallet or bank, only after success; the payee uses it to trace the money with the wallet or bank. Kept after a reversal.

Example: null

customer_ip
stringNullableRequired

The IP address the payee used to submit the payout request in your system; null for disbursements created in the merchant portal.

Example: 203.0.113.10

status
stringRequired

Disbursement status. Clients must not treat an unknown status as success; treat it as not finished and query it.

  • processing: accepted, and the amount plus fee are held; the money is being paid or the outcome isn't confirmed yet. This isn't a failure
  • succeeded: the disbursement succeeded; the amount paid may be less than amount, and the difference is back in settleable
  • failed: the disbursement clearly failed, and the amount and fee are back in settleable; terminal state
  • reversed: sent back by the payee's wallet or bank after it succeeded, so the payee didn't receive the money; the principal and fee are back in settleable; terminal state
  • processing: Accepted, and the amount plus fee are held; the money is being paid or the outcome isn't confirmed yet. This isn't a failure
  • succeeded: The disbursement succeeded; the amount paid may be less than amount, and the difference is back in settleable
  • failed: The disbursement clearly failed, and the amount and fee are back in settleable; terminal state
  • reversed: Sent back by the payee's wallet or bank after it succeeded, so the payee didn't receive the money; the principal and fee are back in settleable; terminal state
  • More values may be added in the future. Don't treat a status you don't recognize as success.

Example: processing

resolution_status
stringRequired

Outcome confirmation.

  • known: outcome confirmed
  • needs_query: outcome unknown; the platform is running a status query against the provider using the original identifiers
  • manual_review: past the automatic query window and handed over to manual follow-up; never marked as failed automatically
  • known: Outcome confirmed
  • needs_query: Outcome unknown; the platform is running a status query against the provider using the original identifiers
  • manual_review: Past the automatic query window and handed over to manual follow-up; never marked as failed automatically
  • More values may be added in the future. Don't treat a status you don't recognize as success.

Example: known

failure
DisbursementFailureNullableRequired

The reason when status is failed; otherwise null.

code
stringRequired

Failure reason code; see x-failure-codes.disbursement for the values. Tolerate new values, and handle any code you don't recognize as upstream_failed.

Example: payee_account_invalid

message
stringRequired

Sanitized description.

Example: Invalid payee account or name mismatch.

paid_amount
integer(int64)NullableRequired

Amount paid, only after success. It may be less than amount, and the difference is back in settleable; kept after a reversal.

Constraints: ≥ 0

Example: null

succeeded_at
string(date-time)NullableRequired

The time the disbursement succeeded; kept after a reversal.

Example: null

failed_at
string(date-time)NullableRequired

The time the disbursement failed.

Example: null

reversed_at
string(date-time)NullableRequired

The time the disbursement was reversed.

Example: null

description
stringNullableRequired

Disbursement description, for your own reconciliation.

Constraints: Max length 256

Example: Sample disbursement

metadata
objectNo

Custom key-value pairs set by the merchant: up to 20 keys. A key can be up to 40 characters, and a value is a string of up to 200 characters. Don't put sensitive data such as card numbers in it. The platform checks for such data and rejects the request.

Constraints: Up to 20 keysMax value length 200

Example: {"business_order_type":"one_time_purchase"}

source
stringRequired

Disbursement source.

  • api: API
  • portal: merchant portal, single
  • batch: merchant portal, batch
  • api: API
  • portal: Merchant portal (single)
  • batch: Merchant portal (batch)
  • More values may be added in the future. Don't treat a status you don't recognize as success.

Example: api

batch_id
stringNullableRequired

Batch ID (dsbb_), only for disbursements created by a batch in the merchant portal.

Example: null

created_at
string(date-time)Required

The time the request was accepted.

Example: 2026-10-29T08:00:00Z

updated_at
string(date-time)Required

The time of the latest change.

Example: 2026-10-29T08:00:00Z

A disbursement isn't a payout: a disbursement pays a third-party payee you choose, while a payout is the platform paying your settlement to your own payout account. For field-by-field notes and examples, see Disbursements.

Disbursement status flow
Disbursement status flow
  • While the outcome is unknown, the status stays processing and resolution_status is needs_query or manual_review. The platform never marks it failed on its own.
  • failed and reversed are final. There's no cancel or retry; to pay again, create a new disbursement with a new merchant disbursement ID.
  • On failure or reversal, the amount and fee go back to the settleable balance (see Status and outcomes).

Event

A merchant event. When the same event is retried, its ID and payload don't change. It never contains full card numbers, CVCs, server-side keys or authentication secrets.

NameTypeRequiredDescription
id
stringRequired

Event ID, used for deduplication.

Example: evt_demo_001

type
stringRequired

Event type. For the values, see EventType in webhooks.v1.yaml; clients must tolerate unknown types.

Example: payment.succeeded

api_version
stringRequired

The API version of the payload.

Example: v1

created_at
string(date-time)Required

The time the event was created. Don't use it in place of the signature time.

Example: 2026-09-23T09:05:00Z

environment
stringRequired

Environment: test is the test environment and live is the live environment. Test and live objects are isolated from each other.

  • test
  • live
  • More values may be added in the future. Don't treat a status you don't recognize as success.

Example: test

merchant_id
stringRequired

Merchant ID.

Example: mer_demo_001

data
EventDataRequired
object
objectRequired

A snapshot of the business object (Payment, Refund, Dispute, Settlement or Disbursement) at the time of the event. It contains only the minimum necessary data the merchant is allowed to see, including id and version.

Example: {"id":"pay_demo_001","merchant_order_no":"ORDER-DEMO-001","amount":10000,"currency":"USD","status":"succeeded","latest_attempt_id":"pat_demo_001","version":4}

  • For the values of type, see Webhook event types. Tolerate new types.
  • created_at is the business time, not the signature time. data.object is a snapshot of the object when the event occurred, and it contains at least id and version. For disbursement.* events, it's a Disbursement snapshot.
Was this page helpful?