Charges API
Create a charge
POST /v1/chargesRequest
{
"amount": 12550,
"currency": "TRY",
"paymentMethod": "bank_transfer",
"merchantReference": "order-2026-000045",
"customer": {
"name": "Customer Name",
"email": "customer@example.com",
"phone": "+905551234567"
},
"metadata": { "orderId": "ord_abc" }
}| Field | Type | Required | Notes |
|---|---|---|---|
amount | integer (minor units) | yes | Positive, fits in safe-int range. |
currency | "TRY" | yes | |
paymentMethod | "bank_transfer" | "credit_card_tr" | "credit_card_international" | yes | |
merchantReference | string ≤120 | yes | Unique per organization. |
customer | object | no | Used for receipts and reconciliation. |
metadata | object | no | Echoed in webhooks. ≤8KB serialized. |
Response — 201 Created
{
"id": "ch_01HYPR…",
"amount": "12550",
"currency": "TRY",
"paymentMethod": "bank_transfer",
"merchantReference": "order-2026-000045",
"status": "pending",
"paymentPageUrl": "https://pay.lidya.money/c/01HYPR…",
"providerPaymentId": "pay_01H…",
"createdAt": "2026-05-06T12:00:00.000Z",
"updatedAt": "2026-05-06T12:00:00.000Z"
}Redirect the customer to paymentPageUrl.
Always include
X-Idempotency-Key. Otherwise a transient network failure will create duplicate charges.
Retrieve a charge
GET /v1/charges/{id}Same body shape as create.
List charges
GET /v1/charges?limit=50&cursor=ch_01HYPR…| Query | Default | Notes |
|---|---|---|
limit | 20 | 1–100. |
cursor | — | Opaque — pass back nextCursor to page. |
Response
{
"data": [ /* ChargeView[] */ ],
"nextCursor": "ch_01HYPP…" | null
}Errors
| Code | HTTP | Meaning |
|---|---|---|
validation_failed | 400 | Body didn't pass schema. details.issues[] lists per-field problems. |
unauthorized | 401 | Missing/invalid X-API-Key. |
organization_frozen | 403 | Organization is paused — contact support. |
duplicate_merchant_reference | 409 | A charge with this merchantReference already exists. |
idempotency_key_reuse | 409 | X-Idempotency-Key was used with a different body. |
provider_unavailable | 502 | Acquirer 5xx after retries. Safe to retry with the same idempotency key. |