Settlement Payment Orders

What is this?
Settlement payment orders allow merchants to request manual payouts to their beneficiaries via the POST v1/merchants/settlement-payment-orders, separate from automatic settlements.
The system automatically splits and routes payments between banks based on available balances.

Actors

Merchant — initiates settlement payout requests.

PlexyPay — handles payout orchestration, routing, and webhooks.

Bank / ACS — executes outgoing credit transfers to beneficiaries.

When to use

You need a fully API-only flow.

You want to manually control settlement timing and amounts.

You manage the full user experience and PCI scope.

Security & Prerequisites

Webhooks: expose an HTTPS endpoint to receive asynchronous payout status updates.

Balance routing: handled automatically by PlexyPay.

Idempotency: use a unique requestId to prevent duplicate payouts.

High-level sequence

Merchant → PlexyPay:
Create a settlement payout request using POST v1/merchants/settlement-payment-orders with beneficiary details and amount.

PlexyPay → Merchant (Webhook):
Sends initial status — created.

PlexyPay ↔ Bank / ACS:
Processes the payout and transfers funds to the beneficiary’s account.

PlexyPay → Merchant (Webhook):
Sends the final status — paid or failed, with transaction identifiers.

Notes

Webhooks are the source of truth for payout statuses.

Manual settlement payouts are independent from automatic clearing cycles.

All operations are performed via API only — no dashboard interaction required.

{
  "name": "payment_order.created",
  "merchant_id": "6c0afdee-33ad-4d36-aef1-b4c70508a780",
  "data": {
       "amount": 10000, 
       "status": "created", 
       "currency": "KZT", 
       "merchant_id": "1f071894-7df7-42c1-a9c8-039b876ca592",
       "beneficiary_id": "aed26d75-2c00-49a1-a626-14d45b8f0dfb",
       "payment_order_id": "4854228f-7246-41c3-9b2d-b44aa629ffac"
  }
}

Payment Order Stasuses

payment_order.created - A payment was created and a request was sent to the bank.
payment_order.paid - payment was successfuly paid.
payment_order.failed - payment was failed.

Settlement Payment Order

Settlement Payment Orders#

Actors#

When to use#

Security & Prerequisites#

High-level sequence#

#

Notes#