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

# Iniciar pagamento via PIX

> Gera a cobrança PIX (QR code) de um pedido não pago.

**orderId** `string` *required*

O ID do pedido.

Cada QR code é válido por até 30 minutos (`expires_at`), nunca além da expiração do próprio pedido.
Chamar de novo enquanto o QR code ainda é válido retorna o mesmo. Depois que ele expira,
chamar de novo enquanto o pedido ainda está aberto retorna um novo QR code para o mesmo pedido.

### Resposta

**response** `object`

**Mostrar objeto**

**transaction\_amount** `number`

O valor da cobrança, em BRL.

**external\_reference** `string | null`

O ID do pedido, devolvido como a referência externa do pagamento.

**txid** `string`

O ID da transação PIX.

**expires\_at** `string | null`

Quando este QR code deixa de ser pagável, em ISO 8601 (até 30 minutos depois de gerado, nunca depois da expiração do pedido).

**qrcode** `object`

**Mostrar objeto**

**copy** `string | null`

O código PIX de copia e cola.

**base64** `string | null`

A imagem do QR code, codificada em base64.

```json Response theme={null}
{
  "response": {
    "transaction_amount": 24.9,
    "external_reference": "order-abc123",
    "txid": "9c2b1e3a-...-000",
    "expires_at": "2026-10-13T15:30:00.000Z",
    "qrcode": {
      "copy": "00020126...6304ABCD",
      "base64": "iVBORw0KGgoAAAANSUhEUgAA..."
    }
  }
}
```

### Respostas de erro

**code** `string`

O código de erro que indica o motivo da falha. Valores possíveis:

* `AUTH_TOKEN_MISSING`, `API_KEY_INVALID`, `SESSION_REVOKED`: o header `Authorization` está ausente, a chave de API é inválida ou a sessão do painel foi revogada (`401`).
* `API_KEY_IP_DENIED`, `API_KEY_SCOPE_DENIED`: a chave de API é usada a partir de um IP fora da sua allowlist, ou não tem o escopo que a rota exige (`403`).
* `USER_NOT_FOUND`: o usuário autenticado não foi encontrado.
* `ORDER_NOT_FOUND`: o pedido informado não existe.
* `FORBIDDEN`: o pedido não pertence ao usuário autenticado.
* `ORDER_NOT_PAYABLE`: o pedido já está pago, cancelado ou expirou (400), ou um pagamento com cartão do pedido ainda está sendo confirmado (409).
* `COUPON_PAYMENT_METHOD`: o cupom do pedido não permite PIX.
* `PAYMENT_METHOD_UNAVAILABLE`: o pagamento online está temporariamente indisponível.
* `INVALID_PARAMS`: o `orderId` está malformado.
* `RATE_LIMIT_EXCEEDED`: outro pagamento da conta está sendo iniciado. Tente de novo em instantes.
* `INTERNAL_SERVER_ERROR`: ocorreu um erro inesperado no servidor.

```json Error Response (400) theme={null}
{
  "code": "ORDER_NOT_PAYABLE"
}
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.