Criar um Pix

post

https://{apiHost}/v2/charge/pix

Esse endpoint é utilizado para a geração de uma cobrança Pix.

A criação do Pix é sincrona, porém o registro na instituição financeira é realizada em segundo plano. Sendo assim, o retorno da requisição não irá conter o campo qrcode.

Para receber o qrcode é necessário assinar um webhook para receber o payload completo do Pix quando o registro for confirmado.

Pré-requisito

Para emitir uma cobrança Pix é necessário ter cadastrado em sua conta uma Conta Pix. Todo Pix pertence a uma Conta Pix que representa a instituição de pagamento e a chave que será usada para a emissão do Pix.
A criação da Conta Pix precisa ser feita pela interface web do sistema ou pelo endpoint POST /api/v2/charge/pix_accounts.

Eventos de Webhook

Ao cadastrar um Pix o sistema cria um comando para registrar o PIX na instituição financeira e o evento pix.register.requested é disparado. Após o registro do Pix ser confirmado na instituição o evento pix.register.confirmed é disparado.

O evento pix.db.created também é disparado nesta operação.

Recent Requests

Time	Status	User Agent
Retrieving recent requests…

Loading…

Body Params

Parametros para criação de uma cobrança Pix

amount

number

required

≥ 0.01

Quantia em reais

payer

object

Dados do Pagador

pix_account_uid

uuid

required

UID da Conta Pix

txid

length between 1 and 35

TXID do Pix - Identificador único da transação

expire_at

date-time

required

Data e hora de vencimento. Formato iso8601

revoke_days

1 to 365

Número de dias ativo após o vencimento. OBRIGATÓRIO e deve ser maior que zero quando o Pix possui juros (interest) ou multa (fine) configurados.

message

length ≤ 140

Mensagem de solicitação ao pagador

additional_info

object | null

Informações adicionais para o pagador (máximo 10 pares chave-valor)

registration_kind

string

enum

Defaults to instant

Tipo do Pix.

instant: Imediato (padrão)
billing: Cobrança

Allowed:

custom_data

object | null

Hash com chave e valor no formato JSON.

external_id

string | null

Identificador externo para o Pix

fine_type

integer

enum

Tipo da multa:

0 Sem multa (none)
1 Por valor (amount)
2 Por percentual (percentage)
No retorno os dados vêm no objeto fine.

Allowed:

fine_amount

float

Valor da multa em reais. Obrigatório quando fine_type = amount.

fine_percentage

float

Percentual da multa (0.0 a 100.0). Obrigatório quando fine_type = percentage.

interest_type

integer

enum

Tipo de juros:

0 Não se aplica / isento (none)
1 Valor diário — dias corridos (daily_amount_calendar)
2 Percentual diário — dias corridos (daily_percentage_calendar)
3 Percentual mensal — dias corridos (monthly_percentage_calendar)
4 Percentual anual — dias corridos (yearly_percentage_calendar)
5 Valor diário — dias úteis (daily_amount_business)
6 Percentual diário — dias úteis (daily_percentage_business)
7 Percentual mensal — dias úteis (monthly_percentage_business)
8 Percentual anual — dias úteis (yearly_percentage_business)
No retorno os dados vêm no objeto interest.

interest_amount

float

Valor diário de juros em reais. Obrigatório quando interest_type for por valor (daily_amount_*).

interest_percentage

float

Percentual de juros. Obrigatório quando interest_type for por percentual.

reduction_type

integer

enum

Tipo de abatimento:

1 Por valor (amount)
2 Por percentual (percentage)
3 Não se aplica — remove o abatimento (none)
No retorno os dados vêm no objeto reduction.

Allowed:

reduction_amount

float

Valor do abatimento em reais. Obrigatório quando reduction_type = amount.

reduction_percentage

float

Percentual do abatimento. Obrigatório quando reduction_type = percentage.

discount_type

integer

enum

Tipo de desconto aplicado aos campos discount_* (nulo/ausente = sem desconto):

1 Valor fixo (fixed_amount)
2 Percentual fixo (fixed_percentage)
3 Antecipação por valor — dias corridos (advance_amount_calendar)
4 Antecipação por valor — dias úteis (advance_amount_business)
5 Antecipação por percentual — dias corridos (advance_percentage_calendar)
6 Antecipação por percentual — dias úteis (advance_percentage_business)
As modalidades de antecipação (3–6) aceitam apenas uma faixa. No retorno o tipo vem em discounts.type.

Allowed:

discount_amount

float

Valor do 1º desconto em reais. Obrigatório quando discount_type for por valor.

discount_percentage

float

Percentual do 1º desconto. Obrigatório quando discount_type for por percentual.

discount_days

integer

Dias antes do vencimento em que o 1º desconto é válido.

discount_second_amount

float

Valor do 2º desconto em reais.

discount_second_percentage

float

Percentual do 2º desconto.

discount_second_days

integer

Dias antes do vencimento em que o 2º desconto é válido.

discount_third_amount

float

Valor do 3º desconto em reais.

discount_third_percentage

float

Percentual do 3º desconto.

discount_third_days

integer

Dias antes do vencimento em que o 3º desconto é válido.

ignore_whatsapp

boolean | null

Defaults to false

Nunca enviar este Pix por WhatsApp

password_protected_mode

integer | null

enum

Modo de proteção por senha: 0=desabilitado, 1=últimos 4 dígitos, 2=primeiros 5 dígitos

Allowed:

201Pix criado com dados de cliente

401Falha de autenticação. Token inválido

422Erro de validação