Payouts

What is this?
A two-step flow where the Merchant first saves a user’s card (tokenization only, no validation/charge), then triggers a payout to that tokenized card.

Actors

Merchant — initiates card saving and payouts

PlexyPay — tokenization, orchestration, webhooks

Bank/Network — processes the outgoing credit transfer (payout)

When to use

Send funds to a user’s card (e.g., refunds outside original tx, partner rewards, gig payouts) using a saved card token.

Security & Notes

Card saving does not validate card activity — no auth/charge is made; only tokenization.

Treat webhooks as the source of truth for terminal states.

High-level sequence

Merchant → PlexyPay: Save card POST /v1/cards (tokenize only; creates a customer on Plexy).

PlexyPay → Merchant (Webhook): Card saved — returns cardTokenId (plus basic card meta).

Merchant → PlexyPay: Payout POST /v1/payout with tokenId = cardTokenId and amount.

PlexyPay ↔ Bank/Network: Process the outgoing credit.

PlexyPay → Merchant (Webhook): Final payout status (success / failed) with identifiers.

The save-card endpoint does not run any authorization/validation; it only returns a token later via webhook.

Payouts Integration Flow

Statuses

Payout in Progress

new — A new payout request has been created and queued for processing. Validation and routing checks have not been completed yet.

processing — The payout is being processed by Plexy Pay and/or the payout provider (bank, card scheme, wallet, etc.). The final outcome (settled, rejected, or failed) is not yet known.

Payout Settled

settled — The payout has been successfully paid out to the recipient and confirmed by the payout provider.
Funds have been debited from the merchant’s balance (or source account) and are considered irreversibly settled on the recipient side.

Payout Failed

rejected — The payout was rejected during validation or by the payout provider.
Typical reasons: invalid recipient details, insufficient merchant balance, regulatory/limit checks, or payout not allowed for this destination.
No funds were debited from the merchant’s balance as part of this payout.

failed — The payout failed due to a technical or system error (for example, network timeouts, provider unavailability, or internal error).
You may safely retry the payout (with the same or a new request identifier, depending on your idempotency strategy) after investigating the error_code and error_message.

Final vs Non-Final Statuses

Non-final statuses: new, processing

Final statuses: settled, rejected, failed

Once a payout reaches a final status, it will not transition to another status.

Webhook Example

{
  "name": "transaction.settled",
  "data": {
    "amount": 100,
    "bin": null,
    "brand": null,
    "cardTokenId": null,
    "createdAt": "2025-12-08T13:48:09.127968Z",
    "currency": "KZT",
    "customerId": null,
    "description": "Payout For Alexander",
    "id": "019ife38-3g27-3ebc-9ba8-3f9cd0defffb",
    "last4": null,
    "merchantReference": null,
    "parentTransactionId": null,
    "payerIp": null,
    "paymentLinkId": null,
    "paymentMethod": "card",
    "paymentSessionId": null,
    "recurringType": null,
    "retrievalReferenceNumber": "524947389757",
    "secure3d": null,
    "status": "settled",
    "storeId": "0b4fg5da-a0b5-4g05-9605-d8g61b302af3",
    "terminalId": "aa825b14-524c-1750-9bf2-139eef7eb197",
    "type": "unknown",
    "updatedAt": "2025-12-08T13:48:12.079754Z"
  },
  "postedAt": "2025-12-08T13:48:15.135728094Z"
}

Good practices

Store cardTokenId mapped to your externalUserId.

Log webhooks and reconcile by transactionId/payoutRef.

Actors#

When to use#

Security & Notes#

High-level sequence#

Statuses#

Webhook Example#

Good practices#