> ## Documentation Index
> Fetch the complete documentation index at: https://docs.v2.certopaybrasil.com/llms.txt
> Use this file to discover all available pages before exploring further.

# CertoPay Quickstart: Your First Payment in 4 Steps

> Make your first PIX payment with CertoPay in under 5 minutes. Create a customer, create an order, process a payment, and verify the transaction.

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.

<Tip>
  Always save the `transactionId` from the process response — you'll need it to check status and issue refunds.
</Tip>

## Prerequisites

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

***

<Steps>
  <Step title="Get Your API Key">
    Log in to the [CertoPay Seller Dashboard](https://painel.certopaybrasil.com) 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.

    ```bash theme={null}
    # 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"
    ```

    <Warning>
      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`.
    </Warning>
  </Step>

  <Step title="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.

    <ParamField body="name" type="string" required>
      Buyer's full name.
    </ParamField>

    <ParamField body="email" type="string" required>
      Buyer's email address.
    </ParamField>

    <ParamField body="document" type="string" required>
      Buyer's CPF — 11 digits, numbers only.
    </ParamField>

    <ParamField body="phone" type="string" required>
      Buyer's phone number in Brazilian format, e.g. `(11) 99999-9999`.
    </ParamField>

    ```bash theme={null}
    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`**

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

    <ResponseField name="id" type="string">
      UUID of the newly created customer. Save this — you will use it in the next step.
    </ResponseField>

    <ResponseField name="name" type="string">
      The customer's full name as stored.
    </ResponseField>

    <ResponseField name="email" type="string">
      The customer's email address as stored.
    </ResponseField>

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

  <Step title="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.

    <ParamField body="customerId" type="string" required>
      The `id` of the customer created in Step 2.
    </ParamField>

    <ParamField body="amount" type="integer" required>
      Total order value in centavos (e.g. `29700` = R\$297,00).
    </ParamField>

    ```bash theme={null}
    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`**

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

    <ResponseField name="id" type="string">
      UUID of the order. Pass this as `orderId` in the payment gateway call.
    </ResponseField>

    <ResponseField name="amount" type="integer">
      Confirmed order amount in centavos.
    </ResponseField>

    <ResponseField name="status" type="string">
      Initial order status — always `PENDING` at creation.
    </ResponseField>

    <ResponseField name="createdAt" type="string">
      ISO 8601 timestamp of when the order was created.
    </ResponseField>
  </Step>

  <Step title="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.

    <ParamField body="orderId" type="string" required>
      UUID of the order created in Step 3.
    </ParamField>

    <ParamField body="method" type="string" required>
      Payment method. Use `PIX` for this quickstart. Other valid values: `BOLETO`, `CREDIT_CARD`.
    </ParamField>

    <ParamField body="amount" type="integer" required>
      Payment amount in centavos. Must match the order amount.
    </ParamField>

    <ParamField body="buyerDoc" type="string" required>
      Buyer's CPF (11 digits).
    </ParamField>

    <ParamField body="buyerCellNumber" type="string" required>
      Buyer's mobile phone number, e.g. `(11) 99999-9999`.
    </ParamField>

    <ParamField body="buyerAddress" type="object" required>
      Buyer's address object. Required fields: `postal_code`, `street`, `number`, `neighborhood`, `city`, `state`.
    </ParamField>

    ```bash theme={null}
    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`**

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

    <ResponseField name="transactionId" type="string">
      UUID of the transaction. **Save this immediately** — it is required to poll status and issue refunds.
    </ResponseField>

    <ResponseField name="status" type="string">
      Transaction status. `PENDING` means the QR Code has been generated and is awaiting buyer payment.
    </ResponseField>

    <ResponseField name="pix.emv" type="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.
    </ResponseField>

    <ResponseField name="pix.qrCodeUrl" type="string">
      URL of the rendered QR Code image. Embed this in your checkout page.
    </ResponseField>

    <ResponseField name="pix.expiresAt" type="string">
      ISO 8601 timestamp after which the QR Code is no longer valid.
    </ResponseField>

    <Tip>
      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.
    </Tip>
  </Step>

  <Step title="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](/webhooks) over polling — CertoPay will POST to your endpoint the moment status changes to `PAID`.

    ```bash theme={null}
    curl https://v2.certopaybrasil.com/api/transactions/uuid-da-transacao \
      -H "X-Api-Key: sk_live_sua_chave"
    ```

    **Expected response — `200 OK`**

    ```json theme={null}
    {
      "id": "uuid-da-transacao",
      "orderId": "uuid-do-pedido",
      "method": "PIX",
      "amount": 29700,
      "status": "PAID"
    }
    ```

    <ResponseField name="id" type="string">
      The transaction UUID.
    </ResponseField>

    <ResponseField name="orderId" type="string">
      The UUID of the parent order.
    </ResponseField>

    <ResponseField name="method" type="string">
      Payment method used — `PIX`, `BOLETO`, or `CREDIT_CARD`.
    </ResponseField>

    <ResponseField name="amount" type="integer">
      Transaction amount in centavos.
    </ResponseField>

    <ResponseField name="status" type="string">
      Current transaction status. See the [status lifecycle table](/introduction#transaction-status-lifecycle) for all possible values.
    </ResponseField>

    <Note>
      For production integrations, set up a [webhook endpoint](/webhooks) 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.
    </Note>
  </Step>
</Steps>

***

## What's Next?

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

<CardGroup cols={2}>
  <Card title="PIX Payments" icon="bolt" href="/payments/pix">
    Deep-dive into PIX: expiry configuration, dynamic vs. static QR Codes, and refunds.
  </Card>

  <Card title="Boleto Payments" icon="barcode" href="/payments/boleto">
    Issue boletos with custom due dates and handle delayed settlement.
  </Card>

  <Card title="Credit Card" icon="credit-card" href="/payments/credit-card">
    Authorize, capture, and refund card payments with installment support.
  </Card>

  <Card title="Webhooks" icon="webhook" href="/webhooks">
    Receive real-time payment confirmations on your server endpoint.
  </Card>
</CardGroup>