API da Droppay

curl -X POST "https://droppayofc.net/api/v1/payments/pix" \
  -H "Authorization: Bearer SEU_TOKEN" \
  -H "X-Client-ID: SEU_CLIENT_ID" \
  -H "Idempotency-Key: pedido-1042-pix" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 49.90,
    "payer_name": "Maria Souza",
    "payer_email": "[email protected]",
    "payer_cpf": "52998224725",
    "payer_phone": "5511999999999",
    "reference": "pedido-1042"
  }'

{
  "success": true,
  "data": {
    "transaction_uuid": "9d3f1c1e-6a2b-4d7e-9a51-2f0c8b7e4a10",
    "reference": "pedido-1042",
    "merchant": { "id": 42, "name": "Gateway Exemplo", "email": "[email protected]", "document": "11222333000181", "phone": "5511999999999" },
    "integration": { "client_id": "cli_gateway_01", "name": "Produção", "project": "Gateway Exemplo" },
    "amount": 49.90,
    "fee": 1.50,
    "amount_net": 48.40,
    "status": "pending",
    "pix_code": "000201010212...",
    "qr_code_base64": "data:image/svg+xml;base64,...",
    "expires_at": "2026-10-25T23:30:00-03:00",
    "expires_in_seconds": 86400
  }
}

Guarde transaction_uuid junto do pedido. O vencimento varia por adquirente: trate expires_at da resposta como fonte da verdade. Para confirmar pagamento use webhook deposit.completed ou GET /payments/{uuid}.

Authorization: Bearer SEU_TOKEN
X-Client-ID: SEU_CLIENT_ID
Accept: application/json
Content-Type: application/json

O mesmo token é o segredo dos webhooks. Ele é exibido no painel no momento da criação/rotação e deve ser tratado como segredo.

Respostas: 201 approved; 202 requires_authentication ou processing; 402 declined. Nunca grave número completo ou CVV. Em 3DS, confirme o resultado pela consulta/webhook, não pela URL de retorno.

Envie {"amount": 50.00} para parcial ou corpo vazio para total.

Status: active, paid, expired ou cancelled. Um link pago não pode ser cancelado.

Quando habilitado para a conta, envie "settlement":"usdt" em POST /payments/pix. A consulta da cobrança traz o bloco settlement. A confirmação do Pix continua sendo deposit.completed; entrega cripto usa crypto_settlement.completed.

{
  "amount": 100.00,
  "payer_name": "Maria Souza",
  "payer_email": "[email protected]",
  "payer_cpf": "52998224725",
  "splits": [
    {"email": "[email protected]", "percentage": 20}
  ]
}

Recebedores precisam ser contas aprovadas. E-mails não podem repetir e a soma não pode superar 100%. O split é calculado sobre o líquido após a taxa da Droppay.

Fonte da verdade para uma cobrança. Se estiver aberta, a Droppay tenta conferir a adquirente antes de responder.

Filtros aceitos: status, type (pix|credit), start_date, end_date, reference, page e per_page (1–100).

available_for_withdrawal considera dívida de MED/chargeback e reserva de parceiro. Consultar saldo também pode reconciliar pendências recentes, no máximo uma vez por minuto por conta.

Janela máxima de 31 dias; format=csv também é aceito. Cada linha traz bruto, taxa e líquido; o líquido é o valor realmente creditado ou enviado.

O saldo é reservado atomicamente para impedir duplo gasto. A adquirente é escolhida pelo roteamento; se a primeira estiver indisponível antes do envio, a próxima pode assumir. Em falha explícita, o valor volta ao saldo. Em resultado incerto, o saque fica em processamento para conferência — nunca é reenviado às cegas.

Alias compatível: GET /cashout/{id}. Campos principais: status, amount (líquido), amount_gross (total debitado), fee, payout_amount, pix_key, pix_key_type e reference.

POST /seu-webhook HTTP/1.1
Content-Type: application/json
X-Webhook-Id: 7f89c866-8d5c-4b84-8b8b-2ff8b67c962a
X-Webhook-Event: deposit.completed
X-Webhook-Timestamp: 1792960200
X-Webhook-Signature-V2: t=1792960200,v1=...
X-Webhook-Signature: ...

{"id":"7f89c866-8d5c-4b84-8b8b-2ff8b67c962a","event":"deposit.completed","data":{"transaction_uuid":"...","status":"completed","amount":49.90,"fee":1.50,"amount_net":48.40},"created_at":"2026-10-25T23:30:00-03:00"}

URL deve ser HTTPS pública e responder 2xx em até 10 segundos. Não seguimos redirects. Em erro de conexão ou 5xx, tentamos novamente em cerca de 60s, até 3 tentativas. 4xx é considerado rejeição definitiva.

Eventos podem chegar fora de ordem ou repetidos. Guarde o X-Webhook-Id/id do evento e, em dúvida, consulte a operação pela API.

1. 1. Leia o corpo cru da requisição.
2. 2. Leia t e v1 em X-Webhook-Signature-V2.
3. 3. Calcule HMAC-SHA256(token, t + "." + corpo) e compare em tempo constante.
4. 4. Recuse timestamps com diferença maior que 5 minutos e deduplique pelo ID do evento.

$raw = file_get_contents("php://input");
$header = $_SERVER["HTTP_X_WEBHOOK_SIGNATURE_V2"] ?? "";
preg_match("/t=(\d+),v1=([a-f0-9]{64})/i", $header, $m);
$timestamp = $m[1] ?? "";
$received = strtolower($m[2] ?? "");
if (!$timestamp || abs(time() - (int) $timestamp) > 300) { http_response_code(401); exit; }
$expected = hash_hmac("sha256", $timestamp . "." . $raw, getenv("DROPPAY_API_TOKEN"));
if (!hash_equals($expected, $received)) { http_response_code(401); exit; }
http_response_code(204);

Expiração: o estado persistido é cancelled; quando o motivo for vencimento, o evento de falha traz reason: expired. Um Pix cancelado/expirado pode ser reaberto para completed se a adquirente comprovar pagamento posterior.

Por indisponibilidade operacional das adquirentes, um saque processing pode voltar a pending e ficar na fila administrativa sem devolver a reserva naquele instante.

curl "https://droppayofc.net/api/v1/payments/TRANSACTION_UUID" \
  -H "Authorization: Bearer SEU_TOKEN" \
  -H "X-Client-ID: SEU_CLIENT_ID" \
  -H "Accept: application/json"

curl -X POST "https://droppayofc.net/api/v1/cashout/pix" \
  -H "Authorization: Bearer SEU_TOKEN" \
  -H "X-Client-ID: SEU_CLIENT_ID" \
  -H "Idempotency-Key: saque-cliente-7788" \
  -H "Content-Type: application/json" \
  -d '{"amount":150.00,"pix_key":"[email protected]","pix_key_type":"EMAIL","reference":"cliente-7788"}'

No exemplo de saque, R$ 150,00 é o total debitado do saldo; a resposta informa fee e payout_amount/amount líquidos. Se estiver exibindo a tela do Pix, consulte a cobrança a cada 5–10s. Para conciliação de backoffice prefira webhook e uma rotina periódica menos agressiva. Nunca use endpoints inexistentes como /pix, /me ou /wallet.

• • Use Authorization Bearer + X-Client-ID e guarde o token somente no servidor.
• • Cadastre IP do servidor quando usar saque automático.
• • Use Idempotency-Key único por intenção de cobrança e por intenção de saque.
• • Envie payer_phone nas cobranças Pix quando possível e sempre CPF/CNPJ válido.
• • Guarde transaction_uuid e reference no seu pedido.
• • Considere expires_at da resposta como fonte da verdade do vencimento.
• • Libere pedido somente após completed/deposit.completed e confira o valor.
• • No saque, trate amount enviado como total debitado e payout_amount como líquido recebido na chave.
• • Valide X-Webhook-Signature-V2 e deduplique pelo ID do evento.
• • Aceite webhooks fora de ordem; em dúvida consulte GET /payments/{uuid}.
• • Em 429/5xx/timeout, aplique backoff e não duplique operações; reutilize a idempotência.
• • Teste Pix pago, Pix expirado, webhook indisponível, replay de criação, saque aprovado e saque recusado antes de abrir tráfego.
• • Importe o OpenAPI desta página no Postman/Insomnia/SDK e mantenha sua integração somente nas rotas documentadas.