Pedidos e Checkout Público

Os pedidos da BukioPay conectam o catálogo de produtos ao checkout com pagamento PIX. Quando o cliente inicia uma compra, a API valida os produtos e as variações diretamente no catálogo da loja, calcula o valor do pedido e gera uma cobrança PIX associada ao pedido.

Estrutura de um pedido

A resposta da criação pública contém os seguintes campos principais:

Campo	Tipo	Descrição
`order.id`	`string`	UUID interno do pedido.
`order.order_code`	`string`	Código público do pedido.
`order.store_id`	`string`	UUID da loja responsável pelo pedido.
`order.customer_name`	`string`	Nome do cliente.
`order.customer_email`	`string`	E-mail do cliente.
`order.customer_document`	`string`	CPF ou CNPJ do cliente, quando informado.
`order.financial.currency`	`string`	Moeda do pedido. Sempre `BRL`.
`order.financial.price`	`number`	Valor total do pedido em reais.
`order.gateway.type`	`string`	Método de pagamento utilizado. Para PIX, o valor é `PIX`.
`order.gateway.external_id`	`string`	Identificador externo da cobrança associada ao pedido.
`order.status.code`	`string`	Código atual do status do pedido.
`order.status.display`	`string`	Descrição legível do status.
`order.items`	`array`	Itens validados e associados ao pedido.
`order.pix`	`object`	Dados do pagamento PIX. Pode ser `null` se a cobrança ainda não tiver sido confirmada.
`order.created_at`	`string`	Data e hora de criação no formato ISO 8601.
`order.updated_at`	`string`	Data e hora da última atualização no formato ISO 8601.

Os valores financeiros dos pedidos são representados em reais, e não em centavos. Por exemplo, 49.90 representa R$ 49,90.

Não envie o preço dos produtos como fonte de verdade. A BukioPay consulta os produtos e as variações cadastradas na loja e calcula o total do pedido no servidor.

Status dos pedidos

Os principais estados do pedido são:

Status	Descrição
`pending`	Pedido criado e aguardando a confirmação do pagamento.
`paid`	Pagamento confirmado. O pedido pode ser processado e entregue.
`cancelled`	Pedido encerrado sem pagamento, cancelado ou expirado.
`refunded`	Pagamento do pedido estornado.

O fluxo mais comum é:

pending → paid

Quando o pagamento não é concluído:

pending → cancelled

Nunca libere produtos, arquivos, links, serviços ou acessos apenas porque o pedido foi criado. Aguarde o evento payment.paid ou confirme que o pedido está com status paid.

Fluxo de checkout

Cliente seleciona os produtos

O cliente escolhe os produtos e as variações desejadas e informa seus dados pessoais.

Sua aplicação cria o pedido

O frontend envia uma requisição para POST /api/v1/orders/public, incluindo o header X-Store-ID, os dados do cliente e os identificadores dos produtos.

A BukioPay valida o catálogo

A API consulta os produtos e as variações cadastradas, valida estoque e disponibilidade e calcula o valor final do pedido no servidor.

A API gera o pagamento PIX

A resposta contém order.pix.qr_code, order.pix.copy_paste e order.pix.expires_at quando a cobrança PIX é criada com sucesso.

Cliente realiza o pagamento

O cliente escaneia o QR Code ou utiliza o código Copia e Cola no aplicativo bancário.

Sua aplicação recebe a confirmação

Utilize o webhook payment.paid como mecanismo principal para confirmar o pagamento e liberar o pedido.

Criando um checkout público

O checkout público utiliza o seguinte endpoint:

POST /api/v1/orders/public

Esse endpoint não exige Bearer Token. Entretanto, o UUID da loja deve ser enviado no header X-Store-ID.

X-Store-ID: 550e8400-e29b-41d4-a716-446655440000
Content-Type: application/json

Nunca envie uma API Key para o navegador. O checkout público foi criado para ser usado sem expor credenciais privadas.

Corpo da requisição

string

required

Nome completo do cliente.

string

required

E-mail válido do cliente.

string

Telefone do cliente.

string

CPF ou CNPJ do cliente. A API remove automaticamente caracteres de formatação.

array

required

Lista dos produtos incluídos no pedido. O pedido deve possuir pelo menos um item.

string

required

UUID do produto cadastrado na loja.

string

UUID da variação selecionada, quando o produto possuir variações.

number

required

Quantidade desejada. Deve ser maior que zero.

string

Método de pagamento. Para checkout PIX, envie pix. Quando omitido, o padrão é PIX.

string

Código de cupom que deverá ser aplicado ao pedido.

string

Código de atribuição de afiliado, quando aplicável.

string

Alternativa para enviar a chave de idempotência no corpo. O header Idempotency-Key tem prioridade.

Exemplo de requisição

curl -X POST 'https://api.bukiopay.com/api/v1/orders/public' \
  --header 'X-Store-ID: 550e8400-e29b-41d4-a716-446655440000' \
  --header 'Idempotency-Key: checkout_ORDER_123' \
  --header 'Content-Type: application/json' \
  --data '{
    "customerName": "João Silva",
    "customerEmail": "joao@example.com",
    "customerPhone": "5511999999999",
    "customerDocument": "12345678900",
    "paymentMethod": "pix",
    "items": [
      {
        "productId": "6ba7b810-9dad-41d1-80b4-00c04fd430c8",
        "variantId": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
        "quantity": 1
      }
    ]
  }'

Exemplo de resposta

Uma criação pública bem-sucedida retorna 200 OK.

{
  "message": "Pedido criado com sucesso",
  "order": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "order_code": "ABC123DEF456GHI789",
    "store_id": "8f14e45f-ea2f-4a9d-bc52-3d19c9ea6d42",
    "customer_name": "João Silva",
    "customer_email": "joao@example.com",
    "customer_document": "12345678900",
    "financial": {
      "currency": "BRL",
      "price": 49.90
    },
    "gateway": {
      "type": "PIX",
      "external_id": "pix-reference"
    },
    "status": {
      "code": "pending",
      "display": "Pendente"
    },
    "items": [
      {
        "id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
        "product_id": "6ba7b810-9dad-41d1-80b4-00c04fd430c8",
        "variant_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
        "name": "Produto Exemplo",
        "quantity": 1,
        "price": 49.90
      }
    ],
    "pix": {
      "qr_code": "data:image/png;base64,iVBORw0KGgo...",
      "copy_paste": "00020101021226820014br.gov.bcb.pix...",
      "expires_at": "2026-08-15T15:30:00.000Z"
    },
    "created_at": "2026-08-15T14:30:00.000Z",
    "updated_at": "2026-08-15T14:30:00.000Z"
  }
}

O campo order.pix pode ser null quando não for possível confirmar a criação do pagamento. A resposta também pode incluir warning. Nesse caso, não crie outro pedido imediatamente usando uma chave diferente.

Idempotência do checkout

Envie uma chave de idempotência em todas as criações:

Idempotency-Key: checkout_ORDER_123

A chave também pode ser enviada como idempotencyKey no corpo, mas o header tem prioridade.

A API retorna a chave efetiva no header Idempotency-Key.
Um replay seguro preserva o mesmo pedido.
Um replay é indicado por Idempotency-Replayed: true.
Se a mesma chave for reutilizada com dados diferentes, a API retorna 409 Conflict.
Se o pedido ainda estiver sendo processado, a API pode retornar 409 Conflict e Retry-After.
Se a criação do PIX estiver incerta, a API retorna PaymentCreationUnknown e não repete automaticamente o envio.

Se receber PaymentCreationUnknown, não crie outro pedido imediatamente. Utilize a mesma Idempotency-Key e reconcilie o pedido existente.

Exibindo o QR Code

Quando order.pix.qr_code contiver uma Data URL, ela poderá ser utilizada diretamente:

<img
  src="data:image/png;base64,iVBORw0KGgo..."
  alt="QR Code PIX"
/>

Para o código Copia e Cola:

<input
  type="text"
  value="00020101021226820014br.gov.bcb.pix..."
  readonly
  id="pix-copy-paste"
/>

<button
  type="button"
  onclick="navigator.clipboard.writeText(document.getElementById('pix-copy-paste').value)"
>
  Copiar código PIX
</button>

Confirmando o pagamento

Use o webhook payment.paid como mecanismo principal para confirmar o pagamento. O webhook informa a transição financeira em tempo real e deve ser processado de forma idempotente.

{
  "event": "payment.paid",
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "type": "PIX_IN",
    "status": "paid",
    "amount": 49.90,
    "currency": "BRL"
  },
  "requestId": "req_0123456789abcdef",
  "createdAt": "2026-08-15T14:35:00.000Z"
}

A consulta do pedido pode ser utilizada como fallback ou para reconciliação. Evite depender de polling contínuo quando os webhooks estiverem configurados.

Consultando um pedido autenticado

Para consultar os dados completos de um pedido pelo backend, utilize:

GET /api/v1/orders/:id

Esse endpoint requer Bearer Token com o escopo transaction.verify. O parâmetro :id aceita:

UUID interno do pedido;
order_code de 18 caracteres.

curl -X GET 'https://api.bukiopay.com/api/v1/orders/550e8400-e29b-41d4-a716-446655440000' \
  --header 'Authorization: Bearer sk_live_sua_api_key'

Listando pedidos

Para listar os pedidos da loja autenticada, utilize:

GET /api/v1/orders

Esse endpoint exige o escopo transaction.verify. Filtros disponíveis:

Parâmetro	Descrição
`status`	Filtra pelo status do pedido.
`limit`	Quantidade por página. Padrão `50`, máximo `100`.
`offset`	Quantidade de registros ignorados. Padrão `0`.
`search`	Busca por UUID, código do pedido, cliente, pagador ou e-mail.
`dateFrom`	Início inclusivo do período no formato ISO 8601.
`dateTo`	Fim exclusivo do período no formato ISO 8601.
`productIds`	Lista de UUIDs de produtos separados por vírgula.
`onlyAutoApproved`	Use `true` para filtrar pedidos não aprovados manualmente.

Boas práticas

Nunca confie nos preços enviados pelo frontend

Envie apenas os identificadores dos produtos, das variações e as quantidades. A BukioPay consulta o catálogo e calcula os valores no servidor.

Use uma chave de idempotência

Gere uma Idempotency-Key para cada tentativa lógica de checkout e reutilize a mesma chave em retries.

Confirme o pagamento por webhook

Utilize payment.paid como mecanismo principal de confirmação antes de entregar produtos ou liberar acessos.

Não exponha sua API Key

Utilize POST /api/v1/orders/public no frontend com X-Store-ID. Endpoints autenticados e API Keys devem permanecer no backend.

Não entregue o pedido apenas pelo retorno da criação

O retorno da criação confirma que o pedido foi registrado, não que o pagamento foi concluído. Aguarde o status paid.

Pronto para integrar pedidos na sua loja? Consulte a referência completa dos endpoints. Ver endpoints de Pedidos →

Introdução

Conceitos

Pedidos e Checkout Público

Estrutura de um pedido

Status dos pedidos

Fluxo de checkout

Criando um checkout público

Corpo da requisição

Exemplo de requisição

Exemplo de resposta

Idempotência do checkout

Exibindo o QR Code

Confirmando o pagamento

Consultando um pedido autenticado

Listando pedidos

Boas práticas

​Estrutura de um pedido

​Status dos pedidos

​Fluxo de checkout

​Criando um checkout público

​Corpo da requisição

​Exemplo de requisição

​Exemplo de resposta

​Idempotência do checkout

​Exibindo o QR Code

​Confirmando o pagamento

​Consultando um pedido autenticado

​Listando pedidos

​Boas práticas

Estrutura de um pedido

Status dos pedidos

Fluxo de checkout

Criando um checkout público

Corpo da requisição

Exemplo de requisição

Exemplo de resposta

Idempotência do checkout

Exibindo o QR Code

Confirmando o pagamento

Consultando um pedido autenticado

Listando pedidos

Boas práticas