Payments API v2
Beta, in development. Published for review and migration planning. The hosts are not serving traffic. The production contracts are under v1 in the version selector — see Start here.
One API for payins and payouts. The documentation is organized by method: each method page has everything you need for that method — endpoints, request, payer step, statuses, decline reasons, errors and webhooks. Rules that are the same for every method are written once under Common and linked from each method page.
Getting started
| Page | What it gives you |
|---|---|
| Quick start | A card payin and a payout with curl |
| Sandbox | Sandbox keys and the amounts that force each outcome |
| Glossary | Merchant, shop, key, payer, recipient, hold |
| Integration flow | What a complete integration does, step by step |
| Migrating from v1 | Endpoint and status mapping from the v1 contracts |
Methods
| Method | Create | Also on the method page |
|---|---|---|
| Card payin | POST /v2/payins/card |
Payment page with 3DS, hold: capture, void; refund |
| Apple Pay | POST /v2/payins/apple-pay |
Session POST /v2/payins/apple-pay/sessions, refund |
| Google Pay | POST /v2/payins/google-pay |
3DS, refund |
| BLIK | POST /v2/payins/blik |
Confirmation in the banking app; refund (not supported yet) |
| Hosted payment form | POST /v2/pay-sessions |
Card on the payment form: a pay session, then a card payin |
| Card payout | POST /v2/payouts/card |
Balance |
Common
| Topic | What it covers |
|---|---|
| Authentication | Bearer key, key format, environments |
| Transactions | Payins, refunds, payouts; GET /v2/transactions, GET /v2/transactions/{transaction_id}; amounts |
| Statuses | Status sets, finality, rules |
| Payer actions | requires_action and next_action: redirect, await confirmation |
| Idempotency | merchant_reference for creates; capture and void are safe to repeat |
| Errors | Error envelope, codes, retries; decline reasons |
| Refunds | POST /v2/payins/{payin_id}/refunds, the Refund object |
| Webhooks | Events, signature, delivery |
Shops and keys
A key belongs to one shop. A shop is either payin or payout and has one currency. Integrating both directions means two shops and two keys. See Glossary.
Next: Quick start
