# Criar cobrança (/docs/cartao/endpoints/charges/post_charges)

## POST /charges

`POST https://api.payzu.io/v1/charges`

Cria uma nova cobrança com cartão de crédito. - Autenticação 3DS: [3-D Secure](https://docs.payzu.com.br/docs/cartao/three-d-secure). Exige `authenticate` igual a `true` junto de `externalAuthentication`. - Motor antifraude: [Antifraude](https://docs.payzu.com.br/docs/cartao/antifraud). - Moeda estrangeira: [Cobrança internacional](https://docs.payzu.com.br/docs/cartao/international). - Pagamento recorrente: envie o nó `recurrence`, descrito em [Pagamentos recorrentes](https://docs.payzu.com.br/docs/cartao/recurrence). - Idempotência: a rota não deduplica por `externalId`, e cada chamada cria uma cobrança. Num timeout, liste as cobranças do período (`GET /charges` com `startDate` e `endDate`) e procure o seu `externalId` antes de repetir.

### Body params

| Field | Type | Required | Details |
| --- | --- | --- | --- |
| `amount` | number | yes | Valor da cobrança em centavos |
| `customer` | object | yes | Dados do comprador |
| `customer.name` | string | yes | Nome completo do comprador |
| `customer.identity` | string | no | Número do documento de identificação do comprador |
| `customer.identityType` | string | no | Tipo de documento de identificação do comprador |
| `customer.email` | string | no | E-mail do comprador |
| `customer.birthdate` | string | no | Data de nascimento do comprador |
| `customer.phone` | string | no | Número do telefone do comprador |
| `customer.address` | object | no | Endereço de cobrança |
| `customer.address.street` | string | yes | Logradouro do endereço de cobrança |
| `customer.address.number` | string | yes | Número do endereço de cobrança |
| `customer.address.complement` | string | no | Complemento do endereço de cobrança |
| `customer.address.zipCode` | string | yes | Código postal do endereço de cobrança |
| `customer.address.city` | string | yes | Cidade do endereço de cobrança |
| `customer.address.state` | string | yes | Estado do endereço de cobrança |
| `customer.address.country` | string | yes | País do endereço de cobrança |
| `customer.address.district` | string | yes | Bairro do endereço de cobrança |
| `postbackUrl` | string | no | URL que recebe as notificações de status da cobrança. Formato em [Webhooks](https://docs.payzu.com.br/docs/cartao/webhooks) |
| `paymentType` | string | yes | Tipo de pagamento da cobrança. Valores em [Códigos de referência](https://docs.payzu.com.br/docs/cartao/reference-codes) — `creditcard` |
| `cart` | object[] | yes | Carrinho do comprador |
| `cart.name` | string | yes | Nome do produto |
| `cart.quantity` | number | yes | Quantidade do produto |
| `cart.sku` | string | yes | SKU (Stock Keeping Unit - Unidade de Controle de Estoque) do produto |
| `cart.unitPrice` | number | yes | Preço unitário do produto em centavos |
| `creditCardPayment` | object | yes | Definições para o tipo de pagamento: cartão de crédito |
| `creditCardPayment.installments` | number | yes | Número de parcelas. Em cobranças internacionais e em recorrências deve ser 1 |
| `creditCardPayment.card` | object | yes | Detalhes do cartão |
| `creditCardPayment.card.number` | string | yes | Número do cartão de crédito |
| `creditCardPayment.card.holder` | string | yes | Nome do portador impresso no cartão de crédito |
| `creditCardPayment.card.expiration` | string | yes | Data de validade do cartão de crédito |
| `creditCardPayment.card.cvv` | string | yes | Código de segurança no verso do cartão de crédito |
| `creditCardPayment.currency` | string | no | Moeda da cobrança. Em moeda estrangeira, `amount` passa a ser expresso na menor unidade dessa moeda. Lista em [Moedas suportadas](https://docs.payzu.com.br/docs/cartao/currencies) e regras em [Cobrança internacional](https://docs.payzu.com.br/docs/cartao/international) — default: BRL |
| `creditCardPayment.authenticate` | boolean | yes | Define se o comprador será direcionado ao emissor para autenticação do cartão (3DS) |
| `creditCardPayment.externalAuthentication` | object | no | Dados de autenticação 3DS realizada fora da PayZu (autenticação externa) |
| `creditCardPayment.externalAuthentication.cavv` | string | yes | Assinatura retornada nos cenários de sucesso na autenticação |
| `creditCardPayment.externalAuthentication.xid` | string | no | XID retornado no processo de autenticação |
| `creditCardPayment.externalAuthentication.eci` | string | yes | Electronic Commerce Indicator devolvido na autenticação. Tabela em [3-D Secure](https://docs.payzu.com.br/docs/cartao/three-d-secure#tabela-eci) |
| `creditCardPayment.externalAuthentication.version` | string | yes | Versão do 3DS aplicado no processo de autenticação |
| `creditCardPayment.externalAuthentication.referenceId` | string | yes | RequestID retornado no processo de autenticação |
| `creditCardPayment.fraudAnalysis` | object | no | Dados para o motor antifraude. Obrigatório em cobranças internacionais. Regras em [Antifraude](https://docs.payzu.com.br/docs/cartao/antifraud) |
| `creditCardPayment.fraudAnalysis.fingerPrintId` | string | yes | Identificador utilizado para cruzar informações obtidas do dispositivo do comprador |
| `creditCardPayment.fraudAnalysis.browser` | object | yes | Informações sobre o navegador do comprador |
| `creditCardPayment.fraudAnalysis.definedFields` | object[] | yes | Merchant Defined Data (MDD). Lista em [Tabela de MDDs](https://docs.payzu.com.br/docs/cartao/mdds) |
| `recurrence` | object | no | Configuração de pagamento recorrente. A primeira cobrança é criada na hora, os ciclos seguintes são gerados automaticamente e `installments` precisa ser 1. Regras em [Pagamentos recorrentes](https://docs.payzu.com.br/docs/cartao/recurrence) |
| `recurrence.interval` | string | yes | Intervalo entre as cobranças: `Monthly` (mensal) ou `Annual` (anual) — `Monthly`, `Annual` |
| `recurrence.endDate` | string | no | Data final da recorrência no formato `YYYY-MM-DD`. Sem ela, a recorrência segue indefinidamente |
| `externalId` | string | yes | Identificador único gerado externamente |

### Responses

**200** Requisição bem sucedida

| Field | Type | Required | Details |
| --- | --- | --- | --- |
| `id` | string | no | Identificador da cobrança |
| `externalId` | string | no | Identificador único gerado externamente |
| `postbackUrl` | string | no | Url para notificações sobre o status da cobrança |
| `amount` | number | no | Valor da cobrança em centavos |
| `paymentType` | string | no | Tipo de pagamento da cobrança. Valores em [Códigos de referência](https://docs.payzu.com.br/docs/cartao/reference-codes) |
| `createdAt` | string | no | Data de criação da cobrança |
| `updatedAt` | string | no | Data da última atualização da cobrança |
| `customer` | object | no | Dados do comprador |
| `customer.id` | number | no | Identificador do comprador. |
| `customer.name` | string | no | Nome completo do comprador |
| `customer.identity` | string | no | Número do documento de identificação do comprador |
| `customer.identityType` | string | no | Tipo de documento de identificação do comprador |
| `customer.email` | string | no | E-mail do comprador |
| `customer.birthdate` | string | no | Data de nascimento do comprador |
| `customer.phone` | string | no | Número do telefone do comprador |
| `customer.address` | object | no | Endereço de cobrança |
| `customer.address.street` | string | yes | Logradouro do endereço de cobrança |
| `customer.address.number` | string | yes | Número do endereço de cobrança |
| `customer.address.complement` | string | no | Complemento do endereço de cobrança |
| `customer.address.zipCode` | string | yes | Código postal do endereço de cobrança |
| `customer.address.city` | string | yes | Cidade do endereço de cobrança |
| `customer.address.state` | string | yes | Estado do endereço de cobrança |
| `customer.address.country` | string | yes | País do endereço de cobrança |
| `customer.address.district` | string | yes | Bairro do endereço de cobrança |
| `cart` | object[] | no | Carrinho do comprador |
| `cart.name` | string | yes | Nome do produto |
| `cart.quantity` | number | yes | Quantidade do produto |
| `cart.sku` | string | yes | SKU (Stock Keeping Unit - Unidade de Controle de Estoque) do produto |
| `cart.unitPrice` | number | yes | Preço unitário do produto em centavos |
| `creditCardPayment` | object | no | Detalhes do pagamento com cartão de crédito |
| `creditCardPayment.installments` | number | no | Número de parcelas |
| `creditCardPayment.authenticate` | boolean | no | Indica se o comprador foi direcionado ao emissor para autenticação 3DS |
| `creditCardPayment.currency` | string | no | Moeda da cobrança. Lista em [Moedas suportadas](https://docs.payzu.com.br/docs/cartao/currencies) |
| `creditCardPayment.acquirerTransactionId` | string | no | Identificador da transação na adquirente |
| `creditCardPayment.authorizationCode` | string | no | Código de autorização retornado pela adquirente |
| `creditCardPayment.reasonCode` | number | no | Código do motivo do resultado. Lista em [Status e motivos da transação](https://docs.payzu.com.br/docs/cartao/transaction-status) |
| `creditCardPayment.reasonMessage` | string | no | Mensagem do motivo do resultado. Lista em [Status e motivos da transação](https://docs.payzu.com.br/docs/cartao/transaction-status) |
| `creditCardPayment.status` | integer | no | Status da transação. Lista em [Status e motivos da transação](https://docs.payzu.com.br/docs/cartao/transaction-status) |
| `creditCardPayment.returnCode` | string | no | Código de retorno da adquirente, lido na tabela de [Códigos de erro](https://docs.payzu.com.br/docs/cartao/error-codes). O mesmo número tem outro significado na tabela [ABECS](https://docs.payzu.com.br/docs/cartao/abecs-codes), que é o padrão das bandeiras para recusas. |
| `creditCardPayment.returnMessage` | string | no | Mensagem de retorno da adquirente |
| `creditCardPayment.externalAuthentication` | object | no | Dados da autenticação externa 3DS, quando enviados na criação |
| `creditCardPayment.reversedAmount` | number | no | Valor estornado em centavos, quando houver estorno |
| `creditCardPayment.reversedDate` | string | no | Data do estorno, quando houver |
| `creditCardPayment.chargeId` | string | no | Identificador da cobrança |
| `creditCardPayment.card` | object | no | Detalhes do cartão utilizado na cobrança |
| `creditCardPayment.card.id` | number | no | Identificador do cartão. |
| `creditCardPayment.card.number` | string | no | Número do cartão de crédito |
| `creditCardPayment.card.holder` | string | no | Nome do portador impresso no cartão de crédito |
| `creditCardPayment.card.expiration` | string | no | Data de validade do cartão de crédito |
| `creditCardPayment.card.brand` | string | no | Bandeira do cartão. Valores em [Códigos de referência](https://docs.payzu.com.br/docs/cartao/reference-codes) — `Visa`, `Master`, `Elo`, `Diners`, `Hipercard` |
| `creditCardPayment.chargebacks` | object[] | no | Chargebacks vinculados à cobrança |
| `creditCardPayment.chargebacks.id` | number | no | Identificador do chargeback |
| `creditCardPayment.chargebacks.number` | string | no | Número do chargeback junto à adquirente |
| `creditCardPayment.chargebacks.amount` | number | no | Valor do chargeback em centavos |
| `creditCardPayment.chargebacks.status` | string | no | Status do chargeback. Lista em [Status e motivos da transação](https://docs.payzu.com.br/docs/cartao/transaction-status) — `RECEIVED`, `ACCEPTED`, `DEFENDED` |
| `creditCardPayment.chargebacks.reasonCode` | string | no | Código do motivo informado pela bandeira |
| `creditCardPayment.chargebacks.reasonDescription` | string | no | Descrição do motivo informado pela bandeira |
| `creditCardPayment.chargebacks.issuedAt` | string | no | Data de emissão do chargeback |
| `creditCardPayment.chargebacks.createdAt` | string | no | Data de criação do registro |
| `creditCardPayment.chargebacks.updatedAt` | string | no | Data da última atualização do registro |
| `recurrence` | object | no | Estado de uma recorrência |
| `recurrence.recurrentPaymentId` | string | no | Identificador da recorrência. Use nos endpoints de consulta e gestão de recorrências |
| `recurrence.interval` | string | no | Intervalo configurado — `MONTHLY`, `ANNUAL` |
| `recurrence.status` | string | no | Status da recorrência. Valores em [Pagamentos recorrentes](https://docs.payzu.com.br/docs/cartao/recurrence) — `ACTIVE`, `INACTIVE`, `ENDED` |
| `recurrence.amount` | number | no | Valor de cada ciclo, em centavos |
| `recurrence.nextRecurrency` | string | no | Data da próxima cobrança automática |
| `recurrence.endDate` | string | no | Data final, se informada na criação |
| `recurrenceCycle` | integer | no | Número do ciclo da recorrência a que esta cobrança pertence: 0 é a cobrança inicial, 1..n são os ciclos gerados automaticamente. Presente apenas em cobranças de recorrência |