Developers

Payments API & Webhooks

Integrate Pix charges into your system with the HyperPag API: payment links, Pix checkout and real-time payment webhooks.

Overview

The HyperPag API is REST over HTTPS, URL-versioned (prefix /v1), with JSON responses. Base URL:

Base URL

https://api.hyperpag.com/v1

The healthcheck is public and can be used for monitoring:

Request

curl -X GET https://api.hyperpag.com/v1/health

API Key authentication

Generate keys in the dashboard (Developer → API Keys). Production keys use the hpg_live_ prefix, are scoped per resource and shown only once at creation. Send the key in the Authorization header:

Header (fictitious example key)

Authorization: Bearer hpg_live_EXAMPLE_DO_NOT_USE

Financial write endpoints also require the Idempotency-Key header to prevent duplication on retries.

Payment flow

01Create a payment link (in the dashboard or via API) with a fixed or open amount.
02The payer opens checkout, fills in their details and receives the Pix QR Code + copy-paste code.
03Upon payment, gateway webhook confirmation arrives and the payment becomes PAID.
04The net amount is credited to the ledger and becomes available balance in the dashboard.

Payment webhooks

Register endpoints in the dashboard (Developer → Webhooks) and receive events in real time. Every delivery is HMAC-signed for origin verification, with logs and replay available in the dashboard.

payment.created

New charge created (link, checkout or API).

payment.paid

Payment confirmed — the Pix was received.

payment.failed

Payment processing failed.

payment.canceled

Charge canceled.

payment.refunded

Payment refunded.

payment.expired

Charge expired without payment.

When registering an endpoint, choose which events to receive (or use * for all).

Example payload (illustrative)

{
  "event": "payment.paid",
  "paymentId": "pay_example",
  "status": "PAID",
  "amountCents": 50000
}

Payment statuses

PENDINGPROCESSINGPAIDFAILEDCANCELEDREFUNDEDEXPIRED

Transitions follow a server-side state machine — invalid transitions are rejected and every change is recorded in the payment history.

Security

HTTPS required on every call.
Scoped API Keys with rotation and instant revocation.
Idempotency on financial endpoints (Idempotency-Key header).
HMAC-signed webhooks; validate the signature before processing.
Per-origin rate limiting.

Generate your keys and endpoints in the dashboard: app.hyperpag.com