# Criar cobrança Pix (/docs/conta-digital/endpoints/charges/post_payment)

## POST /transactions/payment

`POST https://api.hub.payzu.com.br/api/v1/transactions/payment`

Escopo: `PAYMENT_WRITE`. Gera uma cobrança e devolve o Pix copia e cola que o seu cliente vai pagar. O código vem em `pix.qrCodeText`. A cobrança nasce `PENDING`; o saldo muda quando o pagamento é confirmado, e a confirmação chega pelo webhook `PAYMENT_PAID`. Limite de requisições: 60 por minuto por credencial e 120 por conta.

### Body params

| Field | Type | Required | Details |
| --- | --- | --- | --- |
| `amount` | integer | yes | Valor da cobrança, inteiro positivo. `1500` = R$ 15,00. Em centavos. |
| `method` | string | yes | Meio de pagamento. Hoje só `PIX`. — `PIX` |
| `description` | string | null | no | Texto exibido para quem paga. — maxLength: 140 |
| `externalRef` | string | null | no | Sua referência para a cobrança, única na conta. Repetir com os mesmos dados devolve a cobrança existente com `200`; com dados diferentes, `409`. — maxLength: 64 |
| `customer` | object | yes | Quem vai pagar. |
| `customer.name` | string | yes | Nome de quem paga. — minLength: 1; maxLength: 80 |
| `customer.document` | string | yes | CPF ou CNPJ, com ou sem pontuação. O dígito verificador é conferido. — minLength: 11 |
| `customer.email` | string | null | no | E-mail de quem paga. — format: email; maxLength: 120 |
| `customer.phone` | string | null | no | Telefone de quem paga. — maxLength: 20 |
| `ipAddress` | string | null | no | IP do comprador na sua loja. Guardado para análise de fraude e contestação; não volta em resposta nem webhook. |
| `metadata` | object | null | no | Objeto livre devolvido como veio nos webhooks `PAYMENT_*` desta cobrança. Até 20 chaves e 4 KB. |
| `callbackUrl` | string | no | URL HTTPS pública que recebe todos os webhooks desta operação, além dos endpoints cadastrados. Até 2048 caracteres. Exige o segredo de callback da conta. — format: uri; maxLength: 2048 |

### Responses

**200** O `externalRef` já tinha uma cobrança com os mesmos dados; ela é devolvida e nada é criado.

| Field | Type | Required | Details |
| --- | --- | --- | --- |
| `id` | string | yes | Identificador da cobrança. A consulta aceita este `id` e o `paymentId` dos webhooks. |
| `method` | string | yes | Meio de pagamento. — `PIX` |
| `status` | string | yes | `PENDING`: aguardando pagamento. `PAID`: paga. `REFUNDED`: estornada por inteiro. `EXPIRED`: venceu sem pagamento. — `PENDING`, `PAID`, `REFUNDED`, `EXPIRED` |
| `amount` | integer | yes | Valor cobrado. Em centavos. |
| `description` | string | null | yes | Texto exibido para quem paga. |
| `serviceFee` | integer | yes | Tarifa do recebimento, descontada do valor. Em centavos. |
| `netAmount` | integer | yes | `amount − serviceFee`: o que é creditado na conta. Em centavos. |
| `refundedAmount` | integer | yes | Quanto já voltou ao pagador, só estornos concluídos. Em centavos. |
| `refundFee` | integer | yes | Tarifa cobrada nos estornos concluídos. Em centavos. |
| `refundInProgressAmount` | integer | yes | Estorno pedido e ainda sendo processado. Em centavos. |
| `refundableAmount` | integer | yes | Quanto ainda pode ser estornado. `0` enquanto a cobrança não foi paga, enquanto um estorno ainda está sendo processado e enquanto há contestação MED aberta. Em centavos. |
| `openInfractionProtocol` | string | null | yes | Protocolo da contestação MED aberta sobre a cobrança. `null` quando não há. |
| `externalRef` | string | null | yes | Sua referência, como enviada. |
| `callbackUrl` | string | null | yes | A `callbackUrl` enviada na criação. `null` quando não foi enviada. |
| `createdAt` | string | yes | Data e hora em ISO 8601, UTC. — format: date-time |
| `paidAt` | string | null | yes | Quando foi paga. `null` até pagar. — format: date-time |
| `refundedAt` | string | null | yes | Quando foi estornada por inteiro. `null` até lá. — format: date-time |
| `pix` | object | null | yes | Dados do Pix da cobrança. |
| `pix.qrCodeText` | string | null | yes | Pix copia e cola (BR Code). O QR Code é desenhado a partir deste texto. |
| `pix.qrCodeUrl` | string | null | yes | Sempre `null`. |
| `pix.qrCodeBase64` | string | null | yes | Sempre `null`. |
| `pix.conciliationId` | string | null | yes | End-to-end do Pix que pagou. `null` até pagar. |
| `customer` | object | null | yes | Pagador como informado na criação. |
| `customer.name` | string | yes | Nome informado. |
| `customer.document` | string | yes | Documento informado, só dígitos. |
| `customer.email` | string | null | yes | E-mail informado. |
| `customer.phone` | string | null | yes | Telefone informado. |
| `payer` | object | null | yes | Quem de fato pagou, como o banco informou. `null` até pagar. |
| `payer.name` | string | null | yes | Nome de quem pagou. |
| `payer.document` | string | null | yes | CPF mascarado (`***.982.247-**`) ou CNPJ formatado. |
| `payer.bankName` | string | null | yes | Instituição de quem pagou. |
| `refunds` | object[] | yes | Estornos da cobrança, do mais recente para o mais antigo. |
| `refunds.id` | string | yes | Identificador do estorno. É o `refundId` dos webhooks `REFUND_COMPLETED` e `REFUND_FAILED`. |
| `refunds.status` | string | yes | `RESERVED`: o valor saiu do saldo disponível. `SENT`: enviado ao banco. `SETTLED`: devolvido ao pagador. `RELEASED`: recusado, com o valor de volta ao saldo. — `RESERVED`, `SENT`, `SETTLED`, `RELEASED` |
| `refunds.amount` | integer | yes | Valor devolvido ao pagador. Em centavos. |
| `refunds.serviceFee` | integer | yes | Tarifa do estorno. Em centavos. |
| `refunds.totalDebited` | integer | yes | `amount + serviceFee`: o que sai da conta. Em centavos. |
| `refunds.endToEndId` | string | null | yes | End-to-end do Pix de devolução. `null` até concluir. |
| `refunds.rejectedReason` | string | null | yes | Mensagem pronta para exibir, preenchida quando o banco recusou o estorno. |
| `refunds.requestedAt` | string | yes | Quando o estorno foi pedido. ISO 8601, UTC. — format: date-time |
| `refunds.settledAt` | string | null | yes | Quando o estorno foi concluído. `null` até concluir. — format: date-time |
| `refunds.releasedAt` | string | null | yes | Quando o valor voltou ao saldo, após recusa. `null` se não houve recusa. — format: date-time |

**201** Cobrança criada.

| Field | Type | Required | Details |
| --- | --- | --- | --- |
| `id` | string | yes | Identificador da cobrança. A consulta aceita este `id` e o `paymentId` dos webhooks. |
| `method` | string | yes | Meio de pagamento. — `PIX` |
| `status` | string | yes | `PENDING`: aguardando pagamento. `PAID`: paga. `REFUNDED`: estornada por inteiro. `EXPIRED`: venceu sem pagamento. — `PENDING`, `PAID`, `REFUNDED`, `EXPIRED` |
| `amount` | integer | yes | Valor cobrado. Em centavos. |
| `description` | string | null | yes | Texto exibido para quem paga. |
| `serviceFee` | integer | yes | Tarifa do recebimento, descontada do valor. Em centavos. |
| `netAmount` | integer | yes | `amount − serviceFee`: o que é creditado na conta. Em centavos. |
| `refundedAmount` | integer | yes | Quanto já voltou ao pagador, só estornos concluídos. Em centavos. |
| `refundFee` | integer | yes | Tarifa cobrada nos estornos concluídos. Em centavos. |
| `refundInProgressAmount` | integer | yes | Estorno pedido e ainda sendo processado. Em centavos. |
| `refundableAmount` | integer | yes | Quanto ainda pode ser estornado. `0` enquanto a cobrança não foi paga, enquanto um estorno ainda está sendo processado e enquanto há contestação MED aberta. Em centavos. |
| `openInfractionProtocol` | string | null | yes | Protocolo da contestação MED aberta sobre a cobrança. `null` quando não há. |
| `externalRef` | string | null | yes | Sua referência, como enviada. |
| `callbackUrl` | string | null | yes | A `callbackUrl` enviada na criação. `null` quando não foi enviada. |
| `createdAt` | string | yes | Data e hora em ISO 8601, UTC. — format: date-time |
| `paidAt` | string | null | yes | Quando foi paga. `null` até pagar. — format: date-time |
| `refundedAt` | string | null | yes | Quando foi estornada por inteiro. `null` até lá. — format: date-time |
| `pix` | object | null | yes | Dados do Pix da cobrança. |
| `pix.qrCodeText` | string | null | yes | Pix copia e cola (BR Code). O QR Code é desenhado a partir deste texto. |
| `pix.qrCodeUrl` | string | null | yes | Sempre `null`. |
| `pix.qrCodeBase64` | string | null | yes | Sempre `null`. |
| `pix.conciliationId` | string | null | yes | End-to-end do Pix que pagou. `null` até pagar. |
| `customer` | object | null | yes | Pagador como informado na criação. |
| `customer.name` | string | yes | Nome informado. |
| `customer.document` | string | yes | Documento informado, só dígitos. |
| `customer.email` | string | null | yes | E-mail informado. |
| `customer.phone` | string | null | yes | Telefone informado. |
| `payer` | object | null | yes | Quem de fato pagou, como o banco informou. `null` até pagar. |
| `payer.name` | string | null | yes | Nome de quem pagou. |
| `payer.document` | string | null | yes | CPF mascarado (`***.982.247-**`) ou CNPJ formatado. |
| `payer.bankName` | string | null | yes | Instituição de quem pagou. |
| `refunds` | object[] | yes | Estornos da cobrança, do mais recente para o mais antigo. |
| `refunds.id` | string | yes | Identificador do estorno. É o `refundId` dos webhooks `REFUND_COMPLETED` e `REFUND_FAILED`. |
| `refunds.status` | string | yes | `RESERVED`: o valor saiu do saldo disponível. `SENT`: enviado ao banco. `SETTLED`: devolvido ao pagador. `RELEASED`: recusado, com o valor de volta ao saldo. — `RESERVED`, `SENT`, `SETTLED`, `RELEASED` |
| `refunds.amount` | integer | yes | Valor devolvido ao pagador. Em centavos. |
| `refunds.serviceFee` | integer | yes | Tarifa do estorno. Em centavos. |
| `refunds.totalDebited` | integer | yes | `amount + serviceFee`: o que sai da conta. Em centavos. |
| `refunds.endToEndId` | string | null | yes | End-to-end do Pix de devolução. `null` até concluir. |
| `refunds.rejectedReason` | string | null | yes | Mensagem pronta para exibir, preenchida quando o banco recusou o estorno. |
| `refunds.requestedAt` | string | yes | Quando o estorno foi pedido. ISO 8601, UTC. — format: date-time |
| `refunds.settledAt` | string | null | yes | Quando o estorno foi concluído. `null` até concluir. — format: date-time |
| `refunds.releasedAt` | string | null | yes | Quando o valor voltou ao saldo, após recusa. `null` se não houve recusa. — format: date-time |

**400** Requisição inválida.

| Field | Type | Required | Details |
| --- | --- | --- | --- |
| `message` | string | yes | Descrição em português, pronta para exibir. Pode mudar a qualquer momento. |
| `code` | string | yes | Código estável do erro. É por ele que o seu sistema decide o que fazer. |
| `details` | object | no | Contexto estruturado do erro, quando existe. |

**401** Credencial ausente, inválida ou expirada.

| Field | Type | Required | Details |
| --- | --- | --- | --- |
| `message` | string | yes | Descrição em português, pronta para exibir. Pode mudar a qualquer momento. |
| `code` | string | yes | Código estável do erro. É por ele que o seu sistema decide o que fazer. |
| `details` | object | no | Contexto estruturado do erro, quando existe. |

**403** Sem permissão: escopo, IP ou operação desabilitada.

| Field | Type | Required | Details |
| --- | --- | --- | --- |
| `message` | string | yes | Descrição em português, pronta para exibir. Pode mudar a qualquer momento. |
| `code` | string | yes | Código estável do erro. É por ele que o seu sistema decide o que fazer. |
| `details` | object | no | Contexto estruturado do erro, quando existe. |

**409** Conflito com o estado atual.

| Field | Type | Required | Details |
| --- | --- | --- | --- |
| `message` | string | yes | Descrição em português, pronta para exibir. Pode mudar a qualquer momento. |
| `code` | string | yes | Código estável do erro. É por ele que o seu sistema decide o que fazer. |
| `details` | object | no | Contexto estruturado do erro, quando existe. |

**412** Falta um passo antes desta operação.

| Field | Type | Required | Details |
| --- | --- | --- | --- |
| `message` | string | yes | Descrição em português, pronta para exibir. Pode mudar a qualquer momento. |
| `code` | string | yes | Código estável do erro. É por ele que o seu sistema decide o que fazer. |
| `details` | object | no | Contexto estruturado do erro, quando existe. |

**422** Recusa de regra de negócio.

| Field | Type | Required | Details |
| --- | --- | --- | --- |
| `message` | string | yes | Descrição em português, pronta para exibir. Pode mudar a qualquer momento. |
| `code` | string | yes | Código estável do erro. É por ele que o seu sistema decide o que fazer. |
| `details` | object | no | Contexto estruturado do erro, quando existe. |

**429** Limite de requisições excedido.

| Field | Type | Required | Details |
| --- | --- | --- | --- |
| `message` | string | yes | Descrição em português, pronta para exibir. Pode mudar a qualquer momento. |
| `code` | string | yes | Código estável do erro. É por ele que o seu sistema decide o que fazer. |
| `details` | object | no | Contexto estruturado do erro, quando existe. |

**502** O banco não respondeu ou recusou.

| Field | Type | Required | Details |
| --- | --- | --- | --- |
| `message` | string | yes | Descrição em português, pronta para exibir. Pode mudar a qualquer momento. |
| `code` | string | yes | Código estável do erro. É por ele que o seu sistema decide o que fazer. |
| `details` | object | no | Contexto estruturado do erro, quando existe. |

**503** Serviço de consulta ou limitador indisponível; nada foi feito.

| Field | Type | Required | Details |
| --- | --- | --- | --- |
| `message` | string | yes | Descrição em português, pronta para exibir. Pode mudar a qualquer momento. |
| `code` | string | yes | Código estável do erro. É por ele que o seu sistema decide o que fazer. |
| `details` | object | no | Contexto estruturado do erro, quando existe. |