Criar Cobrança com Cartão

Pagamentos com cartão de crédito suportam parcelamento e captura automática ou manual.

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 "card"
card.token string Sim Token do cartão (obtido via tokenização)
card.installments integer Não Número de parcelas (padrão: 1)
card.capture boolean Não Capturar automaticamente (padrão: false)
customer object Sim Dados do cliente (obrigatório - name, email, document, phone, address)
customer.address object Sim Endereço de cobrança (billing address) - obrigatório para cartão
customer.address.street string Sim Nome da rua
customer.address.city string Sim Cidade
customer.address.state string Sim Estado (2 caracteres, ex: "SP", "RJ")
customer.address.zipcode string Sim CEP (8 dígitos)
customer.address.number string Não Número do endereço
customer.address.complement string Não Complemento (apto, bloco, etc)
customer.address.neighborhood string Não Bairro
customer.address.country string Não País (padrão: "BR")
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/v1/charges \
  -H "Authorization: Bearer YOUR_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 10000,
    "currency": "BRL",
    "payment_method": "card",
    "card": {
      "token": "tok_xxxxxxxxxxxxx",
      "installments": 1,
      "capture": true
    },
    "customer": {
      "name": "João Silva",
      "email": "[email protected]",
      "document": "12345678909",
      "phone": "47999999999",
      "address": {
        "street": "Rua das Flores",
        "number": "123",
        "complement": "Apto 45",
        "neighborhood": "Centro",
        "city": "São Paulo",
        "state": "SP",
        "zipcode": "01234567",
        "country": "BR"
      }
    },
    "items": [
      {
        "name": "Produto Exemplo",
        "quantity": 1,
        "unit_price": 10000
      }
    ],
    "metadata": {
      "order_id": "12345"
    },
    "external_id": "order_12345",
    "store_id": 1,
    "product_id": 5,
    "callback_url": "https://seusite.com.br/webhook/order-12345"
  }'

Endereço de Cobrança (Obrigatório)

Para pagamentos com cartão, o endereço de cobrança (billing address) é obrigatório. Este é um requisito padrão da indústria para processamento de transações com cartão de crédito.

Estrutura do Endereço

{
  "customer": {
    "address": {
      "street": "Rua das Flores",      // Obrigatório
      "number": "123",                  // Opcional
      "complement": "Apto 45",          // Opcional
      "neighborhood": "Centro",          // Opcional
      "city": "São Paulo",              // Obrigatório
      "state": "SP",                    // Obrigatório (2 caracteres)
      "zipcode": "01234567",            // Obrigatório (8 dígitos)
      "country": "BR"                   // Opcional (padrão: "BR")
    }
  }
}

Validações

Endereço de Entrega (Opcional)

Se o endereço de entrega for diferente do endereço de cobrança, você pode usar o campo shipping:

{
  "shipping": {
    "address": {
      "street": "Avenida Paulista",
      "number": "1000",
      "city": "São Paulo",
      "state": "SP",
      "zipcode": "01310100",
      "country": "BR"
    }
  }
}

Erros Comuns

Se o endereço não for fornecido ou estiver incompleto, você receberá um erro de validação:

{
  "error": "validation_error",
  "code": "customer.address.required",
  "message": "O endereço do cliente é obrigatório para pagamentos com cartão"
}

Tokenização de Cartão

Antes de criar uma cobrança, você precisa tokenizar o cartão usando a Public Key:

POST /v1/tokens/card

Consulte a documentação de autenticação para mais detalhes sobre tokenização.

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 →