Payment Methods
Brazil has a unique payments landscape, and CertoPay supports all three major payment rails used by Brazilian consumers and businesses.PIX
Instant payment network operated by the Banco Central do Brasil. Funds settle in seconds, 24/7/365. Payments are initiated via a scannable QR Code or copy-paste EMV string.
Boleto
A traditional Brazilian banking slip (boleto bancário) that can be paid at any bank branch, ATM, lottery house, or internet banking portal. Settlement typically takes 1–3 business days.
Credit Card
Supports Visa, Mastercard, and Elo. Customers can pay in full or split the total across up to 12 monthly installments (parcelamento).
How the API Is Structured
The CertoPay API is organized around four core resources that reflect the natural lifecycle of a payment. Every request is authenticated via anX-Api-Key header, and all endpoints return standard JSON responses.
| Resource | Base Path | Purpose |
|---|---|---|
| Customers | /api/customers | Create and manage buyer records |
| Orders | /api/orders | Represent a purchase intent with an amount |
| Payment Gateway | /api/payment-gateway/process | Initiate a payment against an order |
| Transactions | /api/transactions | Query and manage transaction state |
Payment Flow Overview
Every payment on CertoPay follows the same four-stage flow, regardless of method. Understanding this model makes it straightforward to integrate any payment type.Create a Customer
Register the buyer’s details — name, email, CPF, and phone number — once. The returned
customerId can be reused for future purchases.Create an Order
Attach the customer to an order by providing their
customerId and the total amount in centavos (e.g., R$297,00 → 29700). The order acts as the intent to purchase.Process the Payment
Submit the order to
/api/payment-gateway/process along with the chosen payment method (PIX, BOLETO, or CREDIT_CARD). CertoPay returns the payment instrument — a PIX QR Code, Boleto barcode, or card authorization result.Key Concepts
Amounts Are in Centavos
All monetary values in the CertoPay API are expressed as integers in centavos (the smallest unit of the Brazilian Real). This avoids floating-point rounding issues.API Key Authentication
Every request must include your secret API key in theX-Api-Key request header. Keys are prefixed with sk_live_ for production and should never be exposed in client-side code. See the Authentication guide for full details.
Idempotency
Payment processing endpoints accept an optionalIdempotency-Key header containing a UUID v4. If the same key is sent in two requests, CertoPay returns the result of the first request without processing the payment twice. This is essential for safely retrying requests after network failures.
Transaction Status Lifecycle
Once a payment is processed, the resulting transaction moves through a well-defined set of statuses. The table below describes every possible state.| Status | Description |
|---|---|
CREATED | Transaction created, awaiting processing |
PENDING | Awaiting payment — PIX QR Code or Boleto has been generated |
AUTHORIZED | Card authorization approved, awaiting capture |
CAPTURED | Card capture confirmed — funds reserved |
PAID | Payment confirmed (PIX or Boleto settled) |
REFUSED | Payment declined by issuer or anti-fraud |
EXPIRED | Payment window closed before the buyer completed payment |
FAILED | An unexpected processing error occurred |
REFUNDED | Full refund successfully completed |
PARTIAL_REFUND | Partial refund successfully completed |
CHARGEBACK | Buyer opened a dispute with their card issuer |
CANCELLED | Transaction was cancelled before settlement |
Not every status applies to every payment method. For example,
AUTHORIZED and CAPTURED are credit card–only states, while PAID is used for PIX and Boleto confirmations.Explore the API
Quickstart
Make your first PIX payment in under 5 minutes with step-by-step curl examples.
PIX Payments
Generate PIX QR Codes, handle expiry, and confirm instant settlements via webhook.
Boleto Payments
Issue boletos with custom due dates and reconcile payments automatically.
Webhooks
Configure your endpoint, verify signatures, and handle every event type.