The Payment Initiation API generates checkout payment links that redirect end users to complete bank-based payments. The API validates the transaction details, creates a pending transaction record, and mints a secure checkout link. All endpoints use the /api/v1/checkout base path.
Endpoints
| Method | Endpoint | Description |
|---|---|---|
POST | /api/v1/checkout/paylink | Generate a checkout payment link for a new transaction |
Payment Flow
- Generate link — Call
POST /paylinkwith the transaction amount, currency, user ID, and project ID. A transaction is created inpendingstatus and a checkout URL is returned. - Redirect user — Direct the end user to the returned checkout URL. The user selects their bank and authorizes the payment.
- Payment processing — Processes the bank payment. The transaction status moves from
pendingtoprocessing. - Completion — Once the bank confirms the payment, the status updates to
successorfailed. The user is redirected to the project's configuredpayment_return_url. - Webhook notification — A
payment.status_changedwebhook event is sent for each status transition.
Related APIs
| API | Usage |
|---|---|
| Transactions | Query transaction status via GET /api/v1/transactions/{transaction_id} or force a status refresh via POST /refresh-status |
| KYC Verification | Not required to generate a payment link — verification state is informational only, and it's your own compliance policy whether to check it before taking payment |
| Projects | Each payment link is scoped to a project, which defines the callback URL and associated operation company |
Prerequisites
Before generating a payment link, ensure:
- Your callback URL is configured —
PUT /auth/client/settings - Your OpCo is activated — the project's OpCo must have
status: activated - The user or business customer exists under your client — verification status is not checked by this endpoint
- Payment link generation is enabled for your client
Required roles
OWNER or OPERATIONS — DEVELOPER role cannot generate payment links. An API credential can generate payment links only if it was created with the OWNER or OPERATIONS role. See Roles and Permissions.
Related guides
- Core Concepts — How OpCos, Projects, Users, and Transactions connect
- Transaction Lifecycle — What happens after the payment link is generated
- KYC Verification Guide — Both verification modes, and how to check status if your own policy requires it
- Error Reference — Common payment errors and fixes
- Sandbox and Testing — Test the full payment flow