Criar Cobrança com Boleto

Boletos bancários são gerados automaticamente com linha digitável e PDF para download.

Endpoint

POST /v1/charges

Parâmetros

Parâmetro	Tipo	Obrigatório	Descrição
`amount`	integer	Sim	Valor em centavos
`payment_method`	string	Sim	Deve ser "boleto"
`customer`	object	Não	Dados do cliente (opcional - name, email, document, phone, address)
`customer.address`	object	Não	Endereço do cliente (opcional para boleto - recomendado se houver entrega física)
`shipping`	object	Não	Endereço de entrega (opcional - use quando diferente do endereço de cobrança)
`items`	array	Não	Itens da transação (name, quantity, unit_price em centavos). Importante: O campo `unit_price` deve ser maior que zero para cada item. Se todos os itens tiverem `unit_price = 0`, o sistema distribuirá automaticamente o valor total (`amount`) entre os itens proporcionalmente.
`metadata`	object	Não	Metadados customizados (chave-valor)
`external_id`	string	Não	ID externo para rastreamento
`store_id`	integer	Não	ID da operação (store) do dashboard. Se não informado, usa a operação padrão do seller (criada automaticamente no cadastro).
`product_id`	integer	Não	ID do produto do dashboard. Opcional, para associar a cobrança a um produto específico.
`callback_url`	string	Não	URL para receber notificações pontuais desta cobrança (além dos webhooks configurados no dashboard)

Exemplo de Requisição

curl -X POST https://api.apexpy.com.br/api/v1/charges \
  -H "Authorization: Bearer YOUR_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 10000,
    "currency": "BRL",
    "payment_method": "boleto",
    "customer": {
        "name": "João Silva",
        "email": "[email protected]",
        "document": "12345678909",
        "address": {
            "street": "Rua das Flores",
            "number": "123",
            "city": "São Paulo",
            "state": "SP",
            "zipcode": "01234567"
        }
    },
    "callback_url": "https://seusite.com.br/webhook/order-12345"
}'

const res = await fetch("https://api.apexpy.com.br/api/v1/charges", {
  method: "POST",
  headers: {
    Authorization: "Bearer YOUR_SECRET_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "amount": 10000,
    "currency": "BRL",
    "payment_method": "boleto",
    "customer": {
        "name": "João Silva",
        "email": "[email protected]",
        "document": "12345678909",
        "address": {
            "street": "Rua das Flores",
            "number": "123",
            "city": "São Paulo",
            "state": "SP",
            "zipcode": "01234567"
        }
    },
    "callback_url": "https://seusite.com.br/webhook/order-12345"
}),
});
const data = await res.json();
console.log(data);

<?php
$ch = curl_init("https://api.apexpy.com.br/api/v1/charges");
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST => "POST",
    CURLOPT_HTTPHEADER => [
        "Authorization: Bearer YOUR_SECRET_KEY",
        "Content-Type: application/json",
    ],
    CURLOPT_POSTFIELDS => json_encode({
    "amount": 10000,
    "currency": "BRL",
    "payment_method": "boleto",
    "customer": {
        "name": "João Silva",
        "email": "[email protected]",
        "document": "12345678909",
        "address": {
            "street": "Rua das Flores",
            "number": "123",
            "city": "São Paulo",
            "state": "SP",
            "zipcode": "01234567"
        }
    },
    "callback_url": "https://seusite.com.br/webhook/order-12345"
}),
]);
print_r(json_decode(curl_exec($ch), true));

import requests

resp = requests.request(
    "POST",
    "https://api.apexpy.com.br/api/v1/charges",
    headers={
        "Authorization": "Bearer YOUR_SECRET_KEY",
        "Content-Type": "application/json",
    },
    json={
    "amount": 10000,
    "currency": "BRL",
    "payment_method": "boleto",
    "customer": {
        "name": "João Silva",
        "email": "[email protected]",
        "document": "12345678909",
        "address": {
            "street": "Rua das Flores",
            "number": "123",
            "city": "São Paulo",
            "state": "SP",
            "zipcode": "01234567"
        }
    },
    "callback_url": "https://seusite.com.br/webhook/order-12345"
},
)
print(resp.json())

Exemplo de Resposta

{
  "success": true,
  "data": {
    "id": "ci_k7m2p9xr4nqs",
    "status": "pending",
    "amount": 10000,
    "payment_method": "boleto",
    "boleto": {
      "linha_digitavel": "34191.09008 01234.567890 12345.678901 2 12345678901234",
      "pdf_url": "https://api.apexpy.com.br/boleto/ci_k7m2p9xr4nqs.pdf",
      "expires_at": "2025-12-01T23:59:59Z"
    }
  }
}

Validade do Boleto

Por padrão, os boletos têm validade de 3 dias corridos. Após o vencimento, o status muda para expired.

Endereço (Opcional)

Para pagamentos com boleto, o endereço é opcional, mas recomendado se houver entrega física de produtos. A estrutura do endereço é a mesma usada para PIX e Cartão.

Consulte a visão geral do Cash In para mais detalhes sobre requisitos de endereço por método de pagamento.

Split de Pagamento

Você pode dividir o recebimento entre múltiplos sellers usando o campo split na requisição. A taxa de Cash In é calculada uma vez e cobrada do seller principal, enquanto os sellers no split recebem o valor líquido proporcional.

Saiba mais sobre Split de Pagamento →