Seu primeiro checkout em 4 passos

Se você quer validar a integração o mais rápido possível, este é o caminho.

Ao final desta página, você terá criado um checkout Pix, exibido os dados do pagamento e entendido como receber o evento checkout.paid.

Antes de começar

Antes de começar, você precisa de:

uma conta em app.troqpay.com
uma chave trq_test_
um backend capaz de enviar HTTP com JSON

Passo 1: gere uma chave de teste no app

Acesse o app.troqpay.com, abra a área de API da sua conta e gere uma chave com prefixo trq_test_.

A TroqPay usa a mesma URL-base para teste e produção. O ambiente é definido pela chave usada na requisição.

Passo 2: crie um checkout Pix

Com o SDK JavaScript:

import { Troqpay } from "@troqpay/sdk";

const troqpay = new Troqpay({
  apiKey: process.env.TROQPAY_API_KEY!,
});

const checkout = await troqpay.checkouts.create(
  {
    amount: 12990,
    description: "Plano Pro",
    externalId: "order_1001",
    expiresIn: 1800,
    customer: {
      name: "Maria Silva",
      email: "maria@example.com",
    },
    metadata: {
      plan: "pro",
    },
  },
  {
    idempotencyKey: "order_1001",
  }
);

Ou com HTTP direto:

curl -X POST https://api.troqpay.com/v1/checkouts \
  -H "Authorization: Bearer trq_test_xxx" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order_1001" \
  -d '{
    "amount": 12990,
    "description": "Plano Pro",
    "externalId": "order_1001",
    "expiresIn": 1800,
    "customer": {
      "name": "Maria Silva",
      "email": "maria@example.com"
    },
    "metadata": {
      "plan": "pro"
    }
  }'

Exemplo de resposta:

{
  "id": "chk_4a8b3c1d5e6f2a9b0c1d",
  "livemode": false,
  "status": "PENDING",
  "amount": 12990,
  "currency": "BRL",
  "description": "Plano Pro",
  "externalId": "order_1001",
  "checkoutUrl": "https://pay.troqpay.com/pay/chk_4a8b3c1d5e6f2a9b0c1d",
  "createdAt": "2026-04-25T14:00:00.000Z",
  "expiresAt": "2026-04-25T14:30:00.000Z",
  "paidAt": null,
  "customer": {
    "name": "Maria Silva",
    "email": "maria@example.com",
    "document": null
  },
  "pix": {
    "copyPaste": "00020101021226840014br.gov.bcb.pix...",
    "qrCodeUrl": "data:image/svg+xml;charset=utf-8,%3Csvg%20xmlns%3D..."
  },
  "settlement": {
    "currency": "BRL",
    "status": "PENDING",
    "amount": null
  },
  "metadata": {
    "plan": "pro"
  }
}

O que você deve esperar da resposta

Checkout criado

status deve começar em PENDING e livemode deve vir como false quando você estiver usando trq_test_.

Pix pronto para exibição

Você recebe pix.copyPaste, pix.qrCodeUrl e checkoutUrl para escolher como quer cobrar.

Identificação do pedido

id e externalId te ajudam a ligar o checkout ao seu próprio sistema.

Liquidação em BRL

settlement.currency é sempre BRL. settlement.status começa em PENDING e avança para AVAILABLE ou COMPLETED conforme o saldo se concretiza.

Passo 3: exiba o Pix para o comprador

Você pode usar qualquer um destes campos:

pix.copyPaste para o botão de copia e cola
pix.qrCodeUrl para renderizar o QR Code
checkoutUrl se quiser levar o cliente para um fluxo hospedado

pix.qrCodeUrl já é a imagem do QR Code pronta para exibir — basta usá-la como src de um <img>. No sandbox ela vem como uma data: URI (imagem embutida na própria resposta); em produção, é a URL da imagem gerada pelo provedor de pagamento.

O que salvar no seu sistema

Salve pelo menos checkout.id, externalId, amount e livemode. Esses quatro campos já resolvem boa parte da sua conciliação e do seu suporte.

Passo 4: receba o evento de pagamento por webhook

Quando o checkout for pago, você vai receber um webhook parecido com este:

{
  "id": "evt_4a8b3c1d5e6f2a9b0c1d2e3f",
  "type": "checkout.paid",
  "createdAt": "2026-04-25T14:02:10.000Z",
  "livemode": false,
  "data": {
    "checkout": {
      "id": "chk_4a8b3c1d5e6f2a9b0c1d",
      "livemode": false,
      "status": "PAID",
      "amount": 12990,
      "currency": "BRL",
      "externalId": "order_1001",
      "checkoutUrl": "https://pay.troqpay.com/pay/chk_4a8b3c1d5e6f2a9b0c1d",
      "paidAt": "2026-04-25T14:02:10.000Z",
      "settlement": {
        "currency": "BRL",
        "status": "AVAILABLE",
        "amount": "129.90"
      }
    }
  }
}

O objeto data.checkout é o checkout completo — a mesma forma retornada por GET /v1/checkouts/{checkoutId}. Veja Webhooks para todos os campos.

Use externalId para ligar o checkout ao pedido do seu sistema e Idempotency-Key para evitar cobranças duplicadas em caso de retry.

Se algum campo não bater com o esperado, abra a página Erros. Cada code lá tem uma dica de próximo passo.

Fluxo resumido

1. Chave

Gere uma trq_test_ no app.

2. Checkout

Crie o checkout pelo backend.

3. Pix

Mostre o QR Code ou o copia e cola para o comprador.

4. Webhook

Marque o pedido como pago quando checkout.paid chegar.

Próximos passos

Autenticação

Entenda como funcionam chaves, ambiente e idempotência.

SDK JavaScript

Use o pacote @troqpay/sdk para integrar pelo backend.

Webhooks

Veja como validar assinatura, processar eventos e lidar com reentregas.

Checkouts Pix

Aprofunde o ciclo de vida da cobrança e os campos mais importantes do recurso.

Produção

Veja o que revisar antes de usar a integração com clientes reais.

Precisa de ajuda para seguir?

Validar no sandbox

Confira o comportamento do checkout e dos webhooks antes de subir tráfego real.

Revisar erros

Entenda o que fazer se o payload for rejeitado ou a autenticação falhar.

Abrir o app

Gere chaves e revise a configuração da sua conta sem sair da docs.

Comece aqui

Quickstart

Seu primeiro checkout em 4 passos

Antes de começar

Passo 1: gere uma chave de teste no app

Passo 2: crie um checkout Pix

O que você deve esperar da resposta

Checkout criado

Pix pronto para exibição

Identificação do pedido

Liquidação em BRL

Passo 3: exiba o Pix para o comprador

O que salvar no seu sistema

Passo 4: receba o evento de pagamento por webhook

Fluxo resumido

1. Chave

2. Checkout

3. Pix

4. Webhook

Próximos passos

Autenticação

SDK JavaScript

Webhooks

Checkouts Pix

Produção

Precisa de ajuda para seguir?

Validar no sandbox

Revisar erros

Abrir o app

​Seu primeiro checkout em 4 passos

​Antes de começar

​Passo 1: gere uma chave de teste no app

​Passo 2: crie um checkout Pix

​O que você deve esperar da resposta

Checkout criado

Pix pronto para exibição

Identificação do pedido

Liquidação em BRL

​Passo 3: exiba o Pix para o comprador

O que salvar no seu sistema

​Passo 4: receba o evento de pagamento por webhook

​Fluxo resumido

1. Chave

2. Checkout

3. Pix

4. Webhook

​Próximos passos

Autenticação

SDK JavaScript

Webhooks

Checkouts Pix

Produção

​Precisa de ajuda para seguir?

Validar no sandbox

Revisar erros

Abrir o app

Seu primeiro checkout em 4 passos

Antes de começar

Passo 1: gere uma chave de teste no app

Passo 2: crie um checkout Pix

O que você deve esperar da resposta

Passo 3: exiba o Pix para o comprador

Passo 4: receba o evento de pagamento por webhook

Fluxo resumido

Próximos passos

Precisa de ajuda para seguir?