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.

Useful next step

Your first 50 confirmed payments are on us.

Start with $5 credit ↗