Processing Payouts — How the flow works

In addition to payments Our platform provides a seamless way to process payouts to your users. With a single API call that includes type: 'payout', you can initiate payouts, collect recipient details through a secure hosted form, and receive real-time status updates via webhooks.

The term 'Payout' will be used further in the documentation - this is a regular Payment with the type 'payout'.

Figure 1 – Payout flow from initiation to completion.

1. Payout initiated
   The merchant initiates a payout from their system.
2. Create payout
   Your back-end calls POST /api/payments with the amount, currency, and type: 'payout' to get the payout form url.
3. Hosted Payout Form
   You redirect the user to the Payout Form where they can securely enter their payout method details.
4. Return to your site
   We redirect the user back to your redirectUrl, carrying the payment ID so you can show the payout status.
5. Poll if you wish
   You can retrieve the payment with GET /api/payments/:id to see whether it is pending, succeeded or failed.
6. Webhook push
   As soon as the status becomes final, we POST a webhook to the URL you supplied, signed with the token for verification.

With just one API call (including the required type: 'payout' parameter) and one webhook, you have everything you need to process payouts, update your records, and provide a seamless experience to your users.

Payouts API

The Payouts API lets you send money to users in your web apps.

Preparation

1. Get a token in the Merchant Dashboard, enable the “Payout” checkbox when generating the token. Keep this token on your server — never expose it in frontend code.
2. Call every endpoint over HTTPS and add the header: Authorization: Bearer <your-token>
3. ‼️ Always include type: 'payout' when composing in your request body to indicate this is a payout transaction. By default, the payment type is 'payin'.
4. (Optional) Add an Idempotency-Key header with a UUID v4 to prevent duplicate payouts if you need to retry the request.

Step 1 — Create a payout

Endpoint

POST /api/payments
Content-Type: application/json

Required body fields

Optional body fields

cURL example

curl -X POST https://example.com/api/payments \
  -H "Authorization: Bearer tk_test_n4912345faza90aefk4c3awf" \
  -H "Idempotency-Key: 3e3f3796-4c3a-41e2-a90a-2c0f3e20b0a1" \
  -H "Content-Type: application/json" \
  -d '{
        "externalId": "3e3f3796-4c3a-41e2-a90a-2c0f3e20b0a1",
        "amount": "10.00",
        "currency": "EUR",
        "type": "payout",
        "description": "Order #1456",
        "customer": { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "User Name" },
        "metadata": { "orderId": 1456 }
      }'

Response 201 Created / 200 OK

{
  "id": "pay_a1b2c3d4",
  "status": "pending",
  "url": "https://example.com/checkin/pay_a1b2c3d4",
  "externalId": "3e3f3796-4c3a-41e2-a90a-2c0f3e20b0a1",
  "amount": "10.00",
  "currency": "EUR",
  "description": "Order #1456",
  "metadata": { "orderId": 1456 },
  "createdAt": "2025-05-27T14:25:00Z"
}

Fields not echoed back: redirectUrl, customer, webhookUrl.

What next?

1. Open url in the browser or WebView — the user sees the hosted checkin page.
2. After filling in the details, we redirect the user to your redirectUrl (if you specified one).
3. We send a webhook with the final status (succeeded / failed).
4. Repeat the same JSON with the same or no Idempotency-Key: you’ll always get the same response, never a duplicate charge.

Other sections

• Service - more information about service work
• Payform - more information about custom payment chechout page
• Payoutform - more information about custom payout checkin page