All methods require GramPay-API-Token. Missing or invalid credentials return 401 UNAUTHORIZED; a token without the required scope returns 403 FORBIDDEN.
GET /api/getMe
Returns { "app_id": "<uuid>", "name": "My Shop", "status": "active" } for the token’s app.
POST /api/createInvoice
| Parameter | Type | Required | Meaning |
|---|---|---|---|
amount | string or number | yes | USD amount greater than zero, at most 2 decimal places; comma is accepted |
public_description | string | no | Buyer-visible text, 1–256 characters; alias description |
internal_note | string | no | Seller-only note, up to 160 characters |
payload | string | no | Your reference returned by API and invoice webhooks |
expires_in | integer | no | Lifetime in seconds, 60–86,400; default 1,800 |
paid_btn_name | string | no | Post-payment button label |
paid_btn_url | string | no | Post-payment button URL |
Idempotency
Idempotency-Key is optional but recommended. It must contain 1–128 letters, digits, -, _, . or :. An identical replay returns the original invoice and Idempotent-Replayed: true; different parameters with the same key return 409 IDEMPOTENCY_KEY_REUSED. Keys are scoped to the app and survive API-token rotation.
Creation errors
| HTTP | Code | Meaning |
|---|---|---|
| 422 | INVALID_AMOUNT | Amount is invalid |
| 422 | INVALID_PARAMS | Another parameter is invalid |
| 422 | ROUTE_NOT_AVAILABLE | No enabled wallet-and-network route |
| 402 | account_not_serviceable | No processing credit or active payment pack; response includes billing |
| 400 | INVALID_IDEMPOTENCY_KEY | Invalid key format |
| 409 | IDEMPOTENCY_KEY_REUSED | Key reused with different parameters |
The 402 body is exceptional: { "error": "account_not_serviceable", "message": …, "billing": { … } } rather than the normal error envelope.
GET /api/getInvoice
Finds an invoice by payload first, otherwise by public_id, hash or id. A payload lookup returns the newest matching invoice. Missing records return 404 INVOICE_NOT_FOUND.
GET /api/getInvoices
Returns 50 newest-first items per page. Parameters: page, status (active/waiting, paid, expired, cancelled) and comma-separated public_ids. Unsupported status values are ignored. The result includes total_count, per_page, total_pages, current_page and items.
POST /api/cancelInvoice
Send { "public_id": "…" }. /api/deleteInvoice is an alias. Only active invoices can be cancelled; otherwise Phoenix returns 409 INVALID_STATUS.
GET /api/getStats
period can be today, yesterday, week, month, previous_month, last_30_days or all_time (default). The result contains volume, created and paid counts, conversion, average_paid_invoice, start_at and end_at.
Invoice object
Core fields are public_id/hash, status, amount_usd, amount_usdt, amount_usdc, paid_token, paid_source (the paid network key), public_description, internal_note, payload, both checkout URLs, tx_hash, created_at, expiration_date, paid_at, cancelled_at and cancel_reason.
Statuses exposed by the serializer are active, paid, expired and cancelled; manually paid invoices are serialized as paid. Monetary values are strings—use decimal types, not floating point, when comparing them.