Identificadores e IDs

A API ApexPy utiliza um sistema padronizado de identificadores únicos para todas as transações. Entender como funcionam esses identificadores é essencial para uma integração confiável.

Cash In (Cobranças)

ID da Cobrança (`id`)

Toda cobrança criada pela API recebe um identificador único e opaco no formato:

ci_[12 caracteres alfanuméricos aleatórios]

Exemplo: ci_k7m2p9xr4nqs

ci_ é o prefixo fixo para Cash In (cobranças: PIX, Cartão, Boleto)
Os 12 caracteres seguintes são gerados aleatoriamente e são únicos globalmente
O ID não é sequencial — não é possível inferir o volume de cobranças a partir dele
Este é o identificador principal para todas as operações na API

⚠️ Importante: O campo id retornado pela API é uma string opaca. Nunca assuma que ele contém ou deriva de um número sequencial. Sempre armazene o valor exato retornado pela API.

External ID (`external_id`)

Você pode enviar um external_id opcional ao criar uma cobrança para associá-la ao ID do pedido no seu sistema:

{
  "amount": 10000,
  "payment_method": "pix",
  "external_id": "pedido_12345",
  "customer": { ... }
}

O external_id é armazenado e retornado nas respostas da API e nos payloads de webhook. É útil para cruzar cobranças da ApexPy com registros no seu sistema.

TXID do PIX (`pix.txid`) — Identificador do Sistema Bancário

Para cobranças PIX, a resposta inclui o campo pix.txid, que é o Transaction ID gerado pela adquirente e registrado no sistema bancário brasileiro (Banco Central).

💡 Recomendação para integrações via callback_url:
O txid é o identificador mais estável para reconciliação de pagamentos PIX. Ao salvar um pedido, sempre armazene o pix.txid retornado na criação da cobrança. O payload do callback_url inclui o txid para que você possa usá-lo como fallback de identificação caso o id principal não seja encontrado no seu banco de dados.

IDs das Adquirentes

Método	Campo na API	Descrição
PIX	`pix.txid`	Transaction ID (TXID) do PIX gerado pela adquirente e registrado no sistema bancário. Imutável após a criação.
Cartão	Uso interno	ID da transação na adquirente de cartão. Armazenado internamente para reconciliação.
Boleto	Uso interno	ID da transação na adquirente de boleto. Armazenado internamente.

Cash Out (Saques)

ID do Saque (`id`)

Todo saque criado pela API recebe um identificador único e opaco no formato:

co_[12 caracteres alfanuméricos aleatórios]

Exemplo: co_n4hpw7zqr2xs

co_ é o prefixo fixo para Cash Out (saques via PIX)
O ID não é sequencial nem derivado de qualquer número interno
Use este ID para consultar o status de um saque

Uso dos IDs na API

Consultar Cobrança

GET /v1/charges/ci_k7m2p9xr4nqs

Reembolsar

POST /v1/charges/ci_k7m2p9xr4nqs/refund

Cancelar

POST /v1/charges/ci_k7m2p9xr4nqs/cancel

Consultar Saque

GET /v1/payouts/co_n4hpw7zqr2xs

Boas Práticas

Armazene o id exato retornado pela API — não transforme nem derive outros valores a partir dele
Para PIX, armazene também o pix.txid — use-o como identificador de fallback ao processar notificações de pagamento via callback_url
Use external_id para mapear cobranças ApexPy com pedidos do seu sistema
Não assuma sequencialidade — os IDs são opacos por design para não revelar informações de volume

Exemplo Completo

// 1. Criar cobrança PIX com external_id e callback_url
POST /v1/charges
{
  "amount": 10000,
  "payment_method": "pix",
  "external_id": "pedido_12345",
  "callback_url": "https://seusite.com.br/pagamento/callback.php",
  "customer": {
    "name": "João Silva",
    "email": "[email protected]",
    "document": "12345678900"
  }
}

// 2. Resposta — salve AMBOS: id e pix.txid
{
  "success": true,
  "data": {
    "id": "ci_k7m2p9xr4nqs",                      // ID ApexPy — salve isso
    "status": "pending",
    "pix": {
      "txid": "E12345678202511281234567890123456",  // TXID bancário — salve isso também
      "emv": "00020126580014br.gov.bcb.pix...",
      "expires_at": "2025-11-28T21:00:00Z"
    }
  }
}

// 3. Quando o pagamento for confirmado, o callback_url receberá:
{
  "id": "ci_k7m2p9xr4nqs",
  "status": "paid",
  "amount": 10000,
  "txid": "E12345678202511281234567890123456"  // Use como fallback de lookup
}