Pular para o conteúdo principal
POST
Criar um pagamento Pix

Autorizações

Authorization
string
header
obrigatório

Chave de API sk_vl_... criada no painel em Desenvolvedores → Chaves de API.

Cabeçalhos

Idempotency-Key
string

Chave única da operação (até 200 caracteres). Repetir com o mesmo corpo devolve o pagamento já criado.

Maximum string length: 200

Corpo

application/json
method
enum<string>
obrigatório

Forma de pagamento. Pela API, só pix.

Opções disponíveis:
pix
amount

Valor da cobrança. Obrigatório sem product_id. Em reais, com até 2 casas e ponto decimal (ex.: "149.90"). Mínimo 0.01.

Pattern: ^\d{1,9}(\.\d{1,2})?$
Exemplo:

"149.90"

product_id
string

Produto do catálogo. O valor passa a ser preço × quantity.

Pattern: ^prod_[A-Za-z0-9_-]{16}$
Exemplo:

"prod_Xk2v9QeR7tLmN3bA"

quantity
integer
padrão:1

Quantidade do produto.

Intervalo obrigatório: 1 <= x <= 10000
currency
enum<string>
padrão:BRL

Moeda.

Opções disponíveis:
BRL
customer_id
string

Cliente associado.

Pattern: ^cus_[A-Za-z0-9_-]{16}$
Exemplo:

"cus_Xk2v9QeR7tLmN3bA"

external_reference
string

O seu identificador (id do pedido, SKU). Até 100 caracteres.

Maximum string length: 100
Exemplo:

"pedido-1001"

description
string

Descrição da cobrança (até 200 caracteres).

Maximum string length: 200
metadata
object

Até 20 pares chave/valor em texto (chave até 40, valor até 500 caracteres). Volta igual nas respostas e nos webhooks.

Exemplo:
expires_in
integer
padrão:3600

Validade do Pix em segundos.

Intervalo obrigatório: 60 <= x <= 86400
splits
object[]

Divide o valor líquido entre negócios do mesmo dono. A soma de share_bps deve ser 10000.

Required array length: 1 - 5 elements

Resposta

Repetição com a mesma Idempotency-Key e o mesmo corpo: o pagamento já criado (header Idempotent-Replayed: true).

id
string
obrigatório

Id do pagamento.

Pattern: ^pay_[A-Za-z0-9_-]{16}$
Exemplo:

"pay_Xk2v9QeR7tLmN3bA"

object
enum<string>
obrigatório

Sempre payment.

Opções disponíveis:
payment
livemode
boolean
obrigatório

true em produção, false no ambiente de teste.

method
enum<string>
obrigatório

Forma de pagamento.

Opções disponíveis:
pix,
card,
boleto
status
enum<string>
obrigatório

Status. requires_payment: aguardando; processing: em análise; succeeded: pago; underpaid/overpaid: pago com valor diferente (em análise); expired; failed; canceled; partially_refunded; refunded; disputed: cartão contestado.

Opções disponíveis:
requires_payment,
processing,
succeeded,
underpaid,
overpaid,
expired,
failed,
canceled,
partially_refunded,
refunded,
disputed
amount
object
obrigatório

Valor cobrado.

fee
object
obrigatório

Taxa da Valora neste pagamento.

created_at
string<date-time>
obrigatório

Criação.

customer_id
string | null

Cliente associado.

external_reference
string | null

O seu identificador.

description
string | null

Descrição da cobrança.

metadata
object

Até 20 pares chave/valor em texto (chave até 40, valor até 500 caracteres). Volta igual nas respostas e nos webhooks.

Exemplo:
refunded_amount
integer

Total já devolvido ao pagador, em centavos.

dispute
object | null

Contestação (chargeback) do cartão.

items
object[]

Cópia do produto no momento da compra.

splits
object[]

Divisão do valor líquido entre negócios do mesmo dono.

expires_at
string<date-time>

Prazo para pagar.

succeeded_at
string<date-time> | null

Quando o pagamento foi confirmado.

pix
object

Só em pagamentos Pix.

card
object

Só em pagamentos com cartão.

boleto
object

Só em pagamentos por boleto.