SaciPix

Referência da API

Todos os endpoints, parâmetros e respostas.

URL base: https://api.sacipix.com. Autentique com Authorization: Bearer e consulte Erros para o significado de cada código. A especificação completa está em openapi.yaml, pronta para importar no Postman ou gerar clientes.

Criar cobrança

POST/v1/charges

Cria uma cobrança Pix e devolve o QR Code, o copia e cola e a página de checkout.

Cabeçalhos

Idempotency-Keystring
Chave única da operação, até 200 caracteres. Veja Idempotência.

Corpo

amountintegerobrigatório
Valor em centavos, de 100 (R$ 1,00) a 100000000 (R$ 1.000.000,00).
referencestring
Identificador no seu sistema, até 120 caracteres.
descriptionstring
Descrição exibida no checkout, até 255 caracteres.
customer.namestring
Nome do pagador, até 120 caracteres.
customer.documentstring
CPF (11 dígitos) ou CNPJ (14 dígitos), só números.
customer.emailstring
E-mail do pagador.
customer.phonestring
Telefone com DDD, 10 a 13 dígitos, só números.
metadataobject
Pares chave e valor em texto, devolvidos na cobrança e nos webhooks. Cada valor com até 500 caracteres.
webhookUrlstring
URL HTTPS que recebe os eventos desta cobrança, além dos endpoints cadastrados no painel.

Erros específicos

invalid_requestaccount_not_activeaccount_blockedamount_limit_exceededidempotency_conflictidempotency_in_progressprovider_unavailableprovider_error

curl -X POST "https://api.sacipix.com/v1/charges" \
  -H "Authorization: Bearer $GATEWAY_API_KEY" \
  -H "Idempotency-Key: pedido-0001" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 15000,
    "reference": "PEDIDO-0001",
    "description": "Plano anual",
    "customer": {
      "name": "Ana Souza",
      "document": "12345678901",
      "email": "ana@example.com"
    }
  }'
Resposta 201
{
  "id": "7c1e4f2a-3b58-4e0d-9a6c-2f8d1b7e5a10",
  "object": "charge",
  "livemode": false,
  "status": "pending",
  "amount": 15000,
  "fee": 0,
  "net": 15000,
  "currency": "BRL",
  "reference": "PEDIDO-0001",
  "description": "Plano anual",
  "customer": {
    "name": "Ana Souza",
    "document": "12345678901",
    "email": "ana@example.com"
  },
  "metadata": {
    "pedido": "0001"
  },
  "pix": {
    "copyPaste": "00020126580014br.gov.bcb.pix0136...",
    "qrCodeBase64": "iVBORw0KGgoAAAANSUhEUg..."
  },
  "checkoutUrl": "https://painel.example.com/pay/7c1e4f2a-3b58-4e0d-9a6c-2f8d1b7e5a10",
  "payer": null,
  "failureReason": null,
  "paidAt": null,
  "refundedAt": null,
  "createdAt": "2026-11-01T15:04:05.000Z"
}

Obter cobrança

GET/v1/charges/{id}

Devolve o estado atual de uma cobrança do mesmo ambiente da chave.

Parâmetros de caminho

iduuidobrigatório
Identificador da cobrança.

Erros específicos

not_found

curl "https://api.sacipix.com/v1/charges/7c1e4f2a-3b58-4e0d-9a6c-2f8d1b7e5a10" \
  -H "Authorization: Bearer $GATEWAY_API_KEY"
Resposta 200
{
  "id": "7c1e4f2a-3b58-4e0d-9a6c-2f8d1b7e5a10",
  "object": "charge",
  "livemode": false,
  "status": "paid",
  "amount": 15000,
  "fee": 299,
  "net": 14701,
  "currency": "BRL",
  "reference": "PEDIDO-0001",
  "description": "Plano anual",
  "customer": {
    "name": "Ana Souza",
    "document": "12345678901",
    "email": "ana@example.com"
  },
  "metadata": {
    "pedido": "0001"
  },
  "pix": {
    "copyPaste": "00020126580014br.gov.bcb.pix0136...",
    "qrCodeBase64": "iVBORw0KGgoAAAANSUhEUg..."
  },
  "checkoutUrl": "https://painel.example.com/pay/7c1e4f2a-3b58-4e0d-9a6c-2f8d1b7e5a10",
  "payer": {
    "name": "Ana Souza",
    "document": "12345678901"
  },
  "failureReason": null,
  "paidAt": "2026-11-01T15:06:12.000Z",
  "refundedAt": null,
  "createdAt": "2026-11-01T15:04:05.000Z"
}

Listar cobranças

GET/v1/charges

Lista as cobranças do ambiente, das mais recentes para as mais antigas.

Parâmetros de consulta

pageinteger
Página, a partir de 1. Padrão: 1.
limitinteger
Itens por página, de 1 a 100. Padrão: 25.
statusstring
Filtra por pending, paid, refunded ou failed.

Erros específicos

invalid_request

curl "https://api.sacipix.com/v1/charges?status=paid&limit=25" \
  -H "Authorization: Bearer $GATEWAY_API_KEY"
Resposta 200
{
  "data": [
    {
      "id": "7c1e4f2a-3b58-4e0d-9a6c-2f8d1b7e5a10",
      "object": "charge",
      "livemode": false,
      "status": "paid",
      "amount": 15000,
      "fee": 299,
      "net": 14701,
      "currency": "BRL",
      "reference": "PEDIDO-0001",
      "description": "Plano anual",
      "customer": {
        "name": "Ana Souza",
        "document": "12345678901",
        "email": "ana@example.com"
      },
      "metadata": {
        "pedido": "0001"
      },
      "pix": {
        "copyPaste": "00020126580014br.gov.bcb.pix0136...",
        "qrCodeBase64": "iVBORw0KGgoAAAANSUhEUg..."
      },
      "checkoutUrl": "https://painel.example.com/pay/7c1e4f2a-3b58-4e0d-9a6c-2f8d1b7e5a10",
      "payer": null,
      "failureReason": null,
      "paidAt": null,
      "refundedAt": null,
      "createdAt": "2026-11-01T15:04:05.000Z"
    }
  ],
  "page": 1,
  "limit": 25,
  "total": 1,
  "hasMore": false
}

Criar saque Pix

POST/v1/payouts

Reserva o valor e a tarifa no saldo e envia o Pix. Em produção, por padrão, o saque aguarda aprovação antes do envio.

Cabeçalhos

Idempotency-Keystringobrigatório
Chave única da operação, até 200 caracteres. Veja Idempotência.

Corpo

amountintegerobrigatório
Valor em centavos que chega ao destino, de 100 a 100000000. A tarifa é somada à reserva.
pixKeystringobrigatório
Chave Pix de destino.
pixKeyTypestringobrigatório
Tipo da chave: cpf, cnpj, email, phone ou random.
documentstring
CPF ou CNPJ do favorecido, só números.
referencestring
Identificador no seu sistema, até 120 caracteres.
webhookUrlstring
URL HTTPS que recebe os eventos deste saque, além dos endpoints cadastrados.

Erros específicos

invalid_requestinsufficient_fundsaccount_not_activeaccount_blockedidempotency_conflict

curl -X POST "https://api.sacipix.com/v1/payouts" \
  -H "Authorization: Bearer $GATEWAY_API_KEY" \
  -H "Idempotency-Key: saque-fornecedor-77" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 50000,
    "pixKey": "financeiro@example.com",
    "pixKeyType": "email",
    "reference": "FORNECEDOR-77"
  }'
Resposta 201
{
  "id": "e4b9a1d6-6f02-4c37-8b15-90d3c7a2f4e8",
  "object": "payout",
  "livemode": true,
  "type": "pix",
  "status": "pending_approval",
  "amount": 50000,
  "fee": 150,
  "currency": "BRL",
  "reference": "FORNECEDOR-77",
  "pix": {
    "key": "financeiro@example.com",
    "keyType": "email",
    "document": null
  },
  "failureReason": null,
  "completedAt": null,
  "createdAt": "2026-11-01T15:04:05.000Z"
}

Obter saque

GET/v1/payouts/{id}

Devolve o estado atual de um saque Pix ou crypto.

Parâmetros de caminho

iduuidobrigatório
Identificador do saque.

Erros específicos

not_found

curl "https://api.sacipix.com/v1/payouts/e4b9a1d6-6f02-4c37-8b15-90d3c7a2f4e8" \
  -H "Authorization: Bearer $GATEWAY_API_KEY"
Resposta 200
{
  "id": "e4b9a1d6-6f02-4c37-8b15-90d3c7a2f4e8",
  "object": "payout",
  "livemode": true,
  "type": "pix",
  "status": "paid",
  "amount": 50000,
  "fee": 150,
  "currency": "BRL",
  "reference": "FORNECEDOR-77",
  "pix": {
    "key": "financeiro@example.com",
    "keyType": "email",
    "document": null
  },
  "failureReason": null,
  "completedAt": "2026-11-01T15:20:44.000Z",
  "createdAt": "2026-11-01T15:04:05.000Z"
}

Listar saques

GET/v1/payouts

Lista saques Pix e crypto do ambiente, dos mais recentes para os mais antigos.

Parâmetros de consulta

pageinteger
Página, a partir de 1. Padrão: 1.
limitinteger
Itens por página, de 1 a 100. Padrão: 25.
statusstring
Filtra por pending_approval, processing, paid, failed ou rejected.

Erros específicos

invalid_request

curl "https://api.sacipix.com/v1/payouts?status=processing" \
  -H "Authorization: Bearer $GATEWAY_API_KEY"
Resposta 200
{
  "data": [
    {
      "id": "e4b9a1d6-6f02-4c37-8b15-90d3c7a2f4e8",
      "object": "payout",
      "livemode": true,
      "type": "pix",
      "status": "processing",
      "amount": 50000,
      "fee": 150,
      "currency": "BRL",
      "reference": "FORNECEDOR-77",
      "pix": {
        "key": "financeiro@example.com",
        "keyType": "email",
        "document": null
      },
      "failureReason": null,
      "completedAt": null,
      "createdAt": "2026-11-01T15:04:05.000Z"
    }
  ],
  "page": 1,
  "limit": 25,
  "total": 1,
  "hasMore": false
}

Cancelar saque

POST/v1/payouts/{id}/cancel

Cancela um saque que ainda aguarda aprovação e devolve a reserva ao saldo. O saque fica com status rejected e failureReason canceled_by_merchant.

Parâmetros de caminho

iduuidobrigatório
Identificador do saque.

Erros específicos

not_foundforbidden

curl -X POST "https://api.sacipix.com/v1/payouts/e4b9a1d6-6f02-4c37-8b15-90d3c7a2f4e8/cancel" \
  -H "Authorization: Bearer $GATEWAY_API_KEY"
Resposta 200
{
  "id": "e4b9a1d6-6f02-4c37-8b15-90d3c7a2f4e8",
  "object": "payout",
  "livemode": true,
  "type": "pix",
  "status": "rejected",
  "amount": 50000,
  "fee": 150,
  "currency": "BRL",
  "reference": "FORNECEDOR-77",
  "pix": {
    "key": "financeiro@example.com",
    "keyType": "email",
    "document": null
  },
  "failureReason": "canceled_by_merchant",
  "completedAt": "2026-11-01T15:08:30.000Z",
  "createdAt": "2026-11-01T15:04:05.000Z"
}

Cotar USDT

GET/v1/crypto/quote

Calcula quanto em reais sai do saldo para um valor em BRL ou USD. A cotação é uma estimativa e não fica travada.

Parâmetros de consulta

amountinteger
Valor em centavos de real, a partir de 100. Informe amount ou amountUsd.
amountUsdinteger
Valor em centavos de dólar, a partir de 500.

Erros específicos

invalid_requestprovider_errorprovider_unavailable

curl "https://api.sacipix.com/v1/crypto/quote?amountUsd=5000" \
  -H "Authorization: Bearer $GATEWAY_API_KEY"
Resposta 200
{
  "symbol": "USDTBRL",
  "priceBrl": 5.5,
  "amount": 27500,
  "amountUsd": 5000,
  "amountCrypto": "50.00",
  "conversionFee": 50,
  "fee": 413,
  "total": 27963
}

Criar saque crypto

POST/v1/crypto/payouts

Reserva o valor no saldo e envia USDT para a carteira. Acompanhe por webhook ou em GET /v1/payouts/{id}.

Cabeçalhos

Idempotency-Keystringobrigatório
Chave única da operação, até 200 caracteres. Veja Idempotência.

Corpo

amountinteger
Valor em centavos de real, a partir de 100. Informe amount ou amountUsd, nunca os dois.
amountUsdinteger
Valor em centavos de dólar, a partir de 500 (US$ 5,00).
networkstringobrigatório
Rede: TRX, ETH ou BSC.
addressstringobrigatório
Endereço da carteira de destino, de 20 a 120 caracteres.
referencestring
Identificador no seu sistema, até 120 caracteres.
webhookUrlstring
URL HTTPS que recebe os eventos deste saque, além dos endpoints cadastrados.

Erros específicos

invalid_requestamount_below_minimuminsufficient_fundsaccount_not_activeaccount_blockedidempotency_conflictprovider_errorprovider_unavailable

curl -X POST "https://api.sacipix.com/v1/crypto/payouts" \
  -H "Authorization: Bearer $GATEWAY_API_KEY" \
  -H "Idempotency-Key: saque-usdt-0001" \
  -H "Content-Type: application/json" \
  -d '{
    "amountUsd": 5000,
    "network": "TRX",
    "address": "TQn9Y2khEsLJW1ChVWFMSMeRDow5KcbLSE"
  }'
Resposta 201
{
  "id": "e4b9a1d6-6f02-4c37-8b15-90d3c7a2f4e8",
  "object": "payout",
  "livemode": true,
  "type": "crypto",
  "status": "pending_approval",
  "amount": 27500,
  "fee": 413,
  "currency": "BRL",
  "reference": null,
  "crypto": {
    "network": "TRX",
    "address": "TQn9Y2khEsLJW1ChVWFMSMeRDow5KcbLSE",
    "amountUsd": 5000,
    "amountCrypto": null,
    "currency": "USDT",
    "txHash": null
  },
  "failureReason": null,
  "completedAt": null,
  "createdAt": "2026-11-01T15:04:05.000Z"
}

Obter saldo

GET/v1/balance

Devolve o saldo disponível e o valor reservado em saques em andamento.

curl "https://api.sacipix.com/v1/balance" \
  -H "Authorization: Bearer $GATEWAY_API_KEY"
Resposta 200
{
  "object": "balance",
  "livemode": false,
  "currency": "BRL",
  "available": 125000,
  "held": 15150
}

Listar extrato

GET/v1/balance/transactions

Lista cada movimentação do saldo, das mais recentes para as mais antigas.

Parâmetros de consulta

pageinteger
Página, a partir de 1. Padrão: 1.
limitinteger
Itens por página, de 1 a 100. Padrão: 25.

Erros específicos

invalid_request

curl "https://api.sacipix.com/v1/balance/transactions" \
  -H "Authorization: Bearer $GATEWAY_API_KEY"
Resposta 200
{
  "data": [
    {
      "id": 1842,
      "object": "balance_transaction",
      "type": "charge_paid",
      "description": "Pix recebido",
      "amount": 15000,
      "held": 0,
      "balanceAfter": 140000,
      "source": {
        "type": "charge",
        "id": "7c1e4f2a-3b58-4e0d-9a6c-2f8d1b7e5a10"
      },
      "createdAt": "2026-11-01T15:06:12.000Z"
    }
  ],
  "page": 1,
  "limit": 25,
  "total": 1,
  "hasMore": false
}

Listar clientes

GET/v1/customers

Lista pagadores agrupados por documento, com 25 itens por página.

Parâmetros de consulta

qstring
Documento exato, ou parte do nome ou do e-mail.
pageinteger
Página, a partir de 1. Padrão: 1.
curl "https://api.sacipix.com/v1/customers?q=ana" \
  -H "Authorization: Bearer $GATEWAY_API_KEY"
Resposta 200
{
  "data": [
    {
      "document": "12345678901",
      "name": "Ana Souza",
      "email": "ana@example.com",
      "charges": 4,
      "paid": 3,
      "total": 45000,
      "last": "2026-11-01 15:04:05.000+00"
    }
  ],
  "page": 1
}

Simular pagamento

POST/v1/sandbox/charges/{id}/pay

Marca como paga uma cobrança pendente de teste. Credita o saldo de teste e dispara charge.paid.

Parâmetros de caminho

iduuidobrigatório
Identificador da cobrança.

Erros específicos

forbiddennot_foundinvalid_request

curl -X POST "https://api.sacipix.com/v1/sandbox/charges/7c1e4f2a-3b58-4e0d-9a6c-2f8d1b7e5a10/pay" \
  -H "Authorization: Bearer $GATEWAY_API_KEY"
Resposta 200
{
  "id": "7c1e4f2a-3b58-4e0d-9a6c-2f8d1b7e5a10",
  "object": "charge",
  "livemode": false,
  "status": "paid",
  "amount": 15000,
  "fee": 299,
  "net": 14701,
  "currency": "BRL",
  "reference": "PEDIDO-0001",
  "description": "Plano anual",
  "customer": {
    "name": "Ana Souza",
    "document": "12345678901",
    "email": "ana@example.com"
  },
  "metadata": {
    "pedido": "0001"
  },
  "pix": {
    "copyPaste": "00020126580014br.gov.bcb.pix0136...",
    "qrCodeBase64": "iVBORw0KGgoAAAANSUhEUg..."
  },
  "checkoutUrl": "https://painel.example.com/pay/7c1e4f2a-3b58-4e0d-9a6c-2f8d1b7e5a10",
  "payer": {
    "name": "Ana Souza",
    "document": "12345678901"
  },
  "failureReason": null,
  "paidAt": "2026-11-01T15:06:12.000Z",
  "refundedAt": null,
  "createdAt": "2026-11-01T15:04:05.000Z"
}

Simular estorno

POST/v1/sandbox/charges/{id}/refund

Estorna uma cobrança paga de teste. Debita o saldo de teste e dispara charge.refunded.

Parâmetros de caminho

iduuidobrigatório
Identificador da cobrança.

Erros específicos

forbiddennot_foundinvalid_request

curl -X POST "https://api.sacipix.com/v1/sandbox/charges/7c1e4f2a-3b58-4e0d-9a6c-2f8d1b7e5a10/refund" \
  -H "Authorization: Bearer $GATEWAY_API_KEY"
Resposta 200
{
  "id": "7c1e4f2a-3b58-4e0d-9a6c-2f8d1b7e5a10",
  "object": "charge",
  "livemode": false,
  "status": "refunded",
  "amount": 15000,
  "fee": 299,
  "net": 14701,
  "currency": "BRL",
  "reference": "PEDIDO-0001",
  "description": "Plano anual",
  "customer": {
    "name": "Ana Souza",
    "document": "12345678901",
    "email": "ana@example.com"
  },
  "metadata": {
    "pedido": "0001"
  },
  "pix": {
    "copyPaste": "00020126580014br.gov.bcb.pix0136...",
    "qrCodeBase64": "iVBORw0KGgoAAAANSUhEUg..."
  },
  "checkoutUrl": "https://painel.example.com/pay/7c1e4f2a-3b58-4e0d-9a6c-2f8d1b7e5a10",
  "payer": null,
  "failureReason": null,
  "paidAt": "2026-11-01T15:06:12.000Z",
  "refundedAt": "2026-11-01T15:30:00.000Z",
  "createdAt": "2026-11-01T15:04:05.000Z"
}