# 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](/authentication) — API keys and headers
- [Return URL & Webhooks](/return-url-and-webhooks) — buyer redirect vs server notifications
- [API Reference](/api) — 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).

## 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](/return-url-and-webhooks).