Quickstart: authenticate and create an invoice

GramPayBot exposes a small JSON API for invoices and statistics. Status changes can be pushed to your HTTPS endpoint through webhooks.

Create an API token

In the bot open My apps, select an app, then choose 🔑 API → Create token. The gp_live_… token is displayed once. Store it in server-side secrets. Rotate token invalidates the old token; Disable API disables access.

Request format

Methods live under /api. Send the token in the header used by Phoenix:

GramPay-API-Token: gp_live_xxx
Content-Type: application/json

Responses use { "ok": true, "result": … } or { "ok": false, "error": { "code": …, "message": … } } except the special billing 402 response described in the API reference.

Create the first invoice

curl -X POST https://app.grampaybot.com/api/createInvoice \
  -H 'GramPay-API-Token: gp_live_xxx' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: order_184' \
  -d '{"amount":"10.00","public_description":"Access for 30 days","internal_note":"Customer A","payload":"order_184"}'

• public_description is visible to the buyer (description is a legacy alias).
• internal_note is seller-only and is limited to 160 characters.
• payload is your machine-readable reference returned by the API and invoice webhooks.

Use Idempotency-Key to prevent duplicate invoices after timeouts.

Use the result

The result contains a string public_id, status: "active", amounts and two URLs. Send web_app_invoice_url for browser checkout or bot_invoice_url for the Telegram flow. Both open the same invoice in the language configured for the app.

Test the token

curl https://app.grampaybot.com/api/getMe -H 'GramPay-API-Token: gp_live_xxx'

app_id is the app UUID, not a numeric sequence. Next, implement signed webhooks and consult the complete API reference.