Payments API reference
Routes under /api/v1, for a merchant's server. Authenticate with a secret key: Authorization: Bearer sk_test_… or sk_live_…. A platform key with Act for tenants can call them for a tenant with PayLink-Tenant: {slug} and PayLink-Mode: test|live. Guide: Payments API.
OpenAPI document: payments.json. Every PayLink also serves it at /docs/api/payments/openapi.json, with Swagger UI at /docs/api.
/links
POST /api/v1/links
Creates a payment link (a reusable page at /l/{code}). Test keys make test links, live keys live ones.
Body (JSON):
| Field | Type | |
|---|---|---|
title | string | |
description | string | |
amount | integer int64 | |
min_amount | integer int64 | |
max_amount | integer int64 | |
currency | string | |
ask_email | boolean | |
ask_phone | boolean | |
return_url | string | |
max_payments | integer int32 | |
expires_at | string | |
code | string |
GET /api/v1/links
All links for this key's mode.
GET /api/v1/links/{id}
One link, by id or code.
| Parameter | In | Type | |
|---|---|---|---|
id | path | string | required |
POST /api/v1/links/{id}/deactivate
Stops the link taking payments.
| Parameter | In | Type | |
|---|---|---|---|
id | path | string | required |
POST /api/v1/links/{id}/activate
Lets the link take payments again.
| Parameter | In | Type | |
|---|---|---|---|
id | path | string | required |
/payments
POST /api/v1/payments
Creates a payment and returns its checkout_url. Send an Idempotency-Key. Amounts in minor units (paise).
Body (JSON):
| Field | Type | |
|---|---|---|
amount | integer int64 | |
currency | string | |
reference | string | |
description | string | |
customer | object | |
customer.name | string | |
customer.email | string | |
customer.phone | string | |
customer.id | string | |
return_url | string | |
metadata | map of string | |
expires_in | integer int32 |
GET /api/v1/payments
Payments for this key's mode, newest first.
| Parameter | In | Type | |
|---|---|---|---|
status | query | string | |
reference | query | string | |
link_id | query | string | |
limit | query | integer int32 | |
offset | query | integer int32 |
GET /api/v1/payments/{id}
A payment: status, attempts, how it was paid (paid_with) or why it failed (failure), refunds.
| Parameter | In | Type | |
|---|---|---|---|
id | path | string | required |
POST /api/v1/payments/{id}/cancel
Cancels an open payment. A processing payment can't be cancelled: the payer may already have paid.
| Parameter | In | Type | |
|---|---|---|---|
id | path | string | required |
POST /api/v1/payments/{id}/refunds
Refunds all (no amount) or part of a succeeded payment through its gateway.
| Parameter | In | Type | |
|---|---|---|---|
id | path | string | required |
GET /api/v1/payments/{id}/refunds
The payment's refunds.
| Parameter | In | Type | |
|---|---|---|---|
id | path | string | required |
/disputes
GET /api/v1/disputes
Disputes reported by gateways (Razorpay, Stripe, PayPal); payment_id narrows to one payment.
| Parameter | In | Type | |
|---|---|---|---|
payment_id | query | string |
/reporting
GET /api/v1/reporting
The datasets (payments, attempts, refunds, disputes, links, events) and their columns.
GET /api/v1/reporting/{dataset}
Rows of a dataset, with CrudApi's list parameters: filter, orderBy, display, limit, offset, groupBy, count.
| Parameter | In | Type | |
|---|---|---|---|
dataset | path | string | required |
filter | query | string | |
orderBy | query | string | |
display | query | string | |
limit | query | integer int32 | |
offset | query | integer int32 | |
groupBy | query | string | |
count | query | boolean |