CertoPay Quickstart: Your First Payment in 4 Steps

This guide walks you through a complete end-to-end PIX payment using only curl. By the end you will have created a customer record, placed an order, generated a PIX QR Code, and confirmed the transaction status — the same four operations that power every CertoPay integration, regardless of language or framework.

Always save the transactionId from the process response — you’ll need it to check status and issue refunds.

Prerequisites

A CertoPay seller account
Your sk_live_ API key (see Step 1 below)
curl available in your terminal

Get Your API Key

Log in to the CertoPay Seller Dashboard and navigate to Settings → API Keys. Your active key is displayed with a masked suffix. If you have never generated a key, click Create Key — the full secret is shown only once, so copy it immediately and store it in a secure location such as a secrets manager or environment variable.

# Verify your key is working — a 200 response means you're authenticated
curl https://v2.certopaybrasil.com/api/api-keys/me \
  -H "X-Api-Key: sk_live_sua_chave"

Never hard-code your API key in source code or commit it to a repository. Use environment variables (CERTOPAY_API_KEY) and add .env files to your .gitignore.

Create a Customer

A customer represents the buyer. Creating a customer record first lets you associate multiple orders and transactions with the same person over time. You need to supply the buyer’s full name, email address, Brazilian CPF (11-digit tax ID), and phone number.

name

string

required

Buyer’s full name.

string

required

Buyer’s email address.

document

string

required

Buyer’s CPF — 11 digits, numbers only.

phone

string

required

Buyer’s phone number in Brazilian format, e.g. (11) 99999-9999.

curl -X POST https://v2.certopaybrasil.com/api/customers \
  -H "X-Api-Key: sk_live_sua_chave" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "João Silva",
    "email": "joao@email.com",
    "document": "12345678900",
    "phone": "(11) 99999-9999"
  }'

Expected response — 201 Created

{
  "id": "uuid-do-customer",
  "name": "João Silva",
  "email": "joao@email.com"
}

string

UUID of the newly created customer. Save this — you will use it in the next step.

name

string

The customer’s full name as stored.

string

The customer’s email address as stored.

If a customer with the same CPF already exists in your account, the API returns the existing record rather than creating a duplicate.

Create an Order

An order binds a customer to a specific purchase amount. Amounts must be expressed in centavos (integer). For example, R$297,00 becomes 29700. The order does not trigger any payment on its own — it simply establishes intent and is used as the target when you call the payment gateway in the next step.

customerId

string

required

The id of the customer created in Step 2.

amount

integer

required

Total order value in centavos (e.g. 29700 = R$297,00).

curl -X POST https://v2.certopaybrasil.com/api/orders \
  -H "X-Api-Key: sk_live_sua_chave" \
  -H "Content-Type: application/json" \
  -d '{
    "customerId": "uuid-do-customer",
    "amount": 29700
  }'

Expected response — 201 Created

{
  "id": "uuid-do-pedido",
  "customerId": "uuid-do-customer",
  "amount": 29700,
  "status": "PENDING",
  "createdAt": "2026-06-26T10:00:00Z"
}

string

UUID of the order. Pass this as orderId in the payment gateway call.

amount

integer

Confirmed order amount in centavos.

status

string

Initial order status — always PENDING at creation.

createdAt

string

ISO 8601 timestamp of when the order was created.

Process a PIX Payment

With an order in hand, call the payment gateway to generate a PIX QR Code. CertoPay returns an EMV string (the raw PIX payload) and a qrCodeUrl you can render as an image for the buyer to scan. The QR Code expires after 1 hour by default.Include an Idempotency-Key header — a UUID v4 you generate — so the request can be safely retried without creating duplicate charges.

orderId

string

required

UUID of the order created in Step 3.

method

string

required

Payment method. Use PIX for this quickstart. Other valid values: BOLETO, CREDIT_CARD.

amount

integer

required

Payment amount in centavos. Must match the order amount.

buyerDoc

string

required

Buyer’s CPF (11 digits).

buyerCellNumber

string

required

Buyer’s mobile phone number, e.g. (11) 99999-9999.

buyerAddress

object

required

Buyer’s address object. Required fields: postal_code, street, number, neighborhood, city, state.

curl -X POST https://v2.certopaybrasil.com/api/payment-gateway/process \
  -H "X-Api-Key: sk_live_sua_chave" \
  -H "Idempotency-Key: 550e8400-e29b-41d4-a716-446655440001" \
  -H "Content-Type: application/json" \
  -d '{
    "orderId": "uuid-do-pedido",
    "method": "PIX",
    "amount": 29700,
    "buyerDoc": "12345678900",
    "buyerCellNumber": "(11) 99999-9999",
    "buyerAddress": {
      "postal_code": "01310930",
      "street": "Avenida Paulista",
      "number": "100",
      "neighborhood": "Bela Vista",
      "city": "São Paulo",
      "state": "SP"
    }
  }'

Expected response — 201 Created

{
  "transactionId": "uuid-da-transacao",
  "status": "PENDING",
  "method": "PIX",
  "amount": 29700,
  "pix": {
    "emv": "00020126580014br.gov.bcb.pix...",
    "qrCodeUrl": "https://...",
    "expiresAt": "2026-06-26T11:00:00Z"
  }
}

transactionId

string

UUID of the transaction. Save this immediately — it is required to poll status and issue refunds.

status

string

Transaction status. PENDING means the QR Code has been generated and is awaiting buyer payment.

pix.emv

string

The raw PIX EMV/Copia e Cola string. Display this as a text field so the buyer can copy and paste it into their banking app.

pix.qrCodeUrl

string

URL of the rendered QR Code image. Embed this in your checkout page.

pix.expiresAt

string

ISO 8601 timestamp after which the QR Code is no longer valid.

Render both the qrCodeUrl image and the emv copy-paste string in your checkout UI. Many Brazilian buyers prefer to pay via “Pix Copia e Cola” on desktop rather than scanning a QR Code on mobile.

Check the Transaction Status

After presenting the QR Code to the buyer, you can retrieve the current transaction status at any time by calling the Transactions endpoint with the transactionId you saved in Step 4. In production, prefer webhooks over polling — CertoPay will POST to your endpoint the moment status changes to PAID.

curl https://v2.certopaybrasil.com/api/transactions/uuid-da-transacao \
  -H "X-Api-Key: sk_live_sua_chave"

Expected response — 200 OK

{
  "id": "uuid-da-transacao",
  "orderId": "uuid-do-pedido",
  "method": "PIX",
  "amount": 29700,
  "status": "PAID"
}

string

The transaction UUID.

orderId

string

The UUID of the parent order.

method

string

Payment method used — PIX, BOLETO, or CREDIT_CARD.

amount

integer

Transaction amount in centavos.

status

string

Current transaction status. See the status lifecycle table for all possible values.

For production integrations, set up a webhook endpoint so CertoPay pushes status updates to your server in real time. Polling the transactions endpoint works for development and testing, but webhooks are more reliable and efficient for production use.

What’s Next?

You’ve completed a full PIX payment flow. From here you can explore the other payment methods and production-readiness features.

PIX Payments

Deep-dive into PIX: expiry configuration, dynamic vs. static QR Codes, and refunds.

Boleto Payments

Issue boletos with custom due dates and handle delayed settlement.

Credit Card

Authorize, capture, and refund card payments with installment support.

Webhooks

Receive real-time payment confirmations on your server endpoint.

​Prerequisites

​What’s Next?

PIX Payments

Boleto Payments

Credit Card

Webhooks

Prerequisites

What’s Next?