Como criar cobranças com cada método de pagamento
Todos os métodos compartilham os mesmos campos base:
{
"amount": 10000,
"currency": "BRL",
"product_type": "digital",
"customer": {
"name": "Maria Silva",
"email": "maria@email.com",
"tax_id": "12345678901",
"phone": "11999998888",
"type": "individual"
},
"items": [
{
"name": "Curso de Programação",
"quantity": 1,
"unit_price": 10000,
"tangible": false
}
],
"payment_method": "...",
"payment_details": {}
}customer)| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
name | string | Sim | Nome completo |
email | string | Sim | |
tax_id | string | Sim | CPF (11 dígitos) ou CNPJ (14 dígitos) |
phone | string | Sim | Telefone com DDD |
type | string | Sim | individual (PF) ou company (PJ) |
birthdate | string | Não | Data de nascimento |
items)| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
name | string | Sim | Nome do item |
quantity | integer | Sim | Quantidade |
unit_price | integer | Sim | Preço unitário em centavos |
tangible | boolean | Sim | Se é um produto físico |
description | string | Não | Descrição do item |
category | string | Não | Categoria |
code | string | Não | Código SKU |
Para cobranças com cartão de crédito, envie os dados do cartão ou um token no campo payment_details:
curl -X POST https://api.payhubr.com/v1/charges \
-H "Authorization: Basic {credentials}" \
-H "Content-Type: application/json" \
-d '{
"amount": 25000,
"payment_method": "credit_card",
"product_type": "digital",
"customer": {
"name": "Maria Silva",
"email": "maria@email.com",
"tax_id": "12345678901",
"phone": "11999998888",
"type": "individual"
},
"items": [
{ "name": "Curso Online", "quantity": 1, "unit_price": 25000, "tangible": false }
],
payment_details (Cartão de Crédito)| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
number | string | Sim* | Número do cartão |
holder_name | string | Sim* | Nome do titular |
expiration_month | string | Sim* | Mês de expiração (ex: 12) |
expiration_year | string | Sim* | Ano de expiração (ex: 2027) |
cvv | string | Sim* | Código de segurança |
token | string | Sim* | Token do cartão (alternativa aos dados acima) |
installments | integer | Não | Número de parcelas (1-24, padrão: 1) |
statement_descriptor | string | Não | Descrição na fatura (máx. 13 caracteres) |
Envie os dados do cartão (number, holder_name, etc.) ou o token. Se informar o token, os demais campos do cartão são ignorados.
Para cobranças com cartão de débito, envie os mesmos dados de cartão usados no crédito. O parcelamento não é suportado — o valor é sempre cobrado em parcela única.
curl -X POST https://api.payhubr.com/v1/charges \
-H "Authorization: Basic {credentials}" \
-H "Content-Type: application/json" \
-d '{
"amount": 15000,
"payment_method": "debit_card",
"product_type": "digital",
"customer": {
"name": "Maria Silva",
"email": "maria@email.com",
"tax_id": "12345678901",
"phone": "11999998888",
"type": "individual"
},
"items": [
{ "name": "Assinatura Mensal", "quantity": 1, "unit_price": 15000, "tangible": false }
],
payment_details (Cartão de Débito)| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
number | string | Sim* | Número do cartão |
holder_name | string | Sim* | Nome do titular |
expiration_month | string | Sim* | Mês de expiração (ex: 12) |
expiration_year | string | Sim* | Ano de expiração (ex: 2027) |
cvv | string | Sim* | Código de segurança |
token | string | Sim* | Token do cartão (alternativa aos dados acima) |
statement_descriptor | string | Não | Descrição na fatura (máx. 13 caracteres) |
Envie os dados do cartão (number, holder_name, etc.) ou o token. Cartão de débito não suporta parcelamento — o campo installments é ignorado e o valor é sempre cobrado em parcela única.
Cobranças PIX geram um QR Code que o cliente pode pagar instantaneamente:
curl -X POST https://api.payhubr.com/v1/charges \
-H "Authorization: Basic {credentials}" \
-H "Content-Type: application/json" \
-d '{
"amount": 5000,
"payment_method": "pix",
"product_type": "digital",
"customer": {
"name": "João Santos",
"email": "joao@email.com",
"tax_id": "98765432100",
"phone": "11988887777",
"type": "individual"
},
"items": [
{ "name": "E-book", "quantity": 1, "unit_price": 5000, "tangible": false }
],
payment_details (PIX)| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
expires_in_seconds | integer | Não | Tempo de expiração do QR Code em segundos (mínimo: 60) |
A resposta incluirá os dados do PIX para apresentar ao cliente (QR Code, código copia-e-cola, etc.).
Cobranças por boleto geram um boleto bancário com data de vencimento:
curl -X POST https://api.payhubr.com/v1/charges \
-H "Authorization: Basic {credentials}" \
-H "Content-Type: application/json" \
-d '{
"amount": 35000,
"payment_method": "boleto",
"product_type": "physical",
"customer": {
"name": "Ana Costa",
"email": "ana@email.com",
"tax_id": "11122233344",
"phone": "11977776666",
"type": "individual"
},
"billing_address": {
"street": "Rua das Flores",
"number": "100",
payment_details (Boleto)| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
due_date | string | Sim | Data de vencimento (formato YYYY-MM-DD) |
instructions | string | Não | Instruções de pagamento impressas no boleto |
document_number | string | Não | Número do documento |
Além dos campos obrigatórios, você pode enviar dados adicionais em qualquer cobrança:
| Campo | Tipo | Descrição |
|---|---|---|
submerchant_id | string | ID do submerchant (para cobranças em nome de um subcomerciante) |
shipping_amount | integer | Valor do frete em centavos |
billing_address | object | Endereço de cobrança |
shipping_address | object | Endereço de entrega |
metadata | object | Dados adicionais livres (ex: { "order_id": "12345" }) |
split | array | Array de regras de split para dividir o valor entre recebedores (ver documentação) |
const response = await fetch('https://api.payhubr.com/v1/charges', {
method: 'POST',
headers: {
'Authorization': `Basic ${credentials}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
amount: 25000,
payment_method: 'credit_card',
product_type: 'digital',
customer: {
name: 'Maria Silva',
email: 'maria@email.com',
tax_id: '12345678901',
phone: '11999998888',
type: 'individual',
},
items: [
{ name: 'Curso Online', quantity: 1, unit_price: 25000, tangible: false },
],
payment_details: {
number: '4111111111111111',
holder_name: 'MARIA SILVA',
expiration_month: '12',
expiration_year: '2027',
cvv: '123',
installments: 3,
statement_descriptor: 'SOARLABZ',
},
}),
});const response = await fetch('https://api.payhubr.com/v1/charges', {
method: 'POST',
headers: {
'Authorization': `Basic ${credentials}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
amount: 15000,
payment_method: 'debit_card',
product_type: 'digital',
customer: {
name: 'Maria Silva',
email: 'maria@email.com',
tax_id: '12345678901',
phone: '11999998888',
type: 'individual',
},
items: [
{ name: 'Assinatura Mensal', quantity: 1, unit_price: 15000, tangible: false },
],
payment_details: {
number: '4111111111111111',
holder_name: 'MARIA SILVA',
expiration_month: '12',
expiration_year: '2027',
cvv: '123',
statement_descriptor: 'SOARLABZ',
},
}),
});const response = await fetch('https://api.payhubr.com/v1/charges', {
method: 'POST',
headers: {
'Authorization': `Basic ${credentials}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
amount: 5000,
payment_method: 'pix',
product_type: 'digital',
customer: {
name: 'João Santos',
email: 'joao@email.com',
tax_id: '98765432100',
phone: '11988887777',
type: 'individual',
},
items: [
{ name: 'E-book', quantity: 1, unit_price: 5000, tangible: false },
],
payment_details: {
expires_in_seconds: 3600,
},
}),
});const response = await fetch('https://api.payhubr.com/v1/charges', {
method: 'POST',
headers: {
'Authorization': `Basic ${credentials}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
amount: 35000,
payment_method: 'boleto',
product_type: 'physical',
customer: {
name: 'Ana Costa',
email: 'ana@email.com',
tax_id: '11122233344',
phone: '11977776666',
type: 'individual',
},
billing_address: {
street: 'Rua das Flores',
number: '100',
neighborhood: 'Centro',
city: 'São Paulo',
state: 'SP',
zip_code: '01001000',
},
items: [
{ name: 'Camiseta', quantity: 2, unit_price: 15000, tangible: true },
{ name: 'Frete', quantity: 1, unit_price: 5000, tangible: false },
],
payment_details: {
due_date: '2026-03-15',
instructions: 'Não receber após o vencimento',
},
}),
});