PaySwitch API Reference
PaySwitch provides REST APIs to create and manage payments, refunds, customers, and webhooks. Requests and responses use JSON; standard HTTP status codes apply.
Quick links
- Authentication — API keys and headers
- Metadata — custom key/value fields on customers, payments, refunds
- Return URL & Webhooks — buyer redirect vs server notifications
- API Reference — interactive endpoints (generated from OpenAPI)
Environment URLs and authentication basics are also shown on the API Reference landing page (from the OpenAPI info block, rebuilt on each spec generation).
In the interactive API Reference, pick Dev or Production in the server selector before Try it. Use test keys (snd_…) on Dev and live keys (prod_…) on Production.
Payment status lifecycle
| Status | Meaning |
|---|---|
requires_payment_method | Payment created without a payment method attached. |
requires_confirmation | Payment method attached; confirm is required. |
requires_customer_action | Customer must complete 3DS or another redirect step. |
requires_capture | Authorized with manual capture; funds not captured yet. |
processing | Submitted to the processor after confirm (auto-capture flow). |
succeeded | Payment completed successfully. |
failed | Processor reported failure. |
Additional states you may see: partially_captured, partially_captured_and_capturable, expired, cancelled.
Redirect after checkout
After redirect-based flows (3DS, bank, payment link), the buyer is sent to your return URL. PaySwitch appends query parameters such as status, payment_id, and client_secret.
If return_url is omitted on a specific payment, the default from Business Profile (Payment Settings) is used when configured.
Webhooks
For reliable server-side status updates, configure Webhook URL on the business profile. See Return URL & Webhooks.