Documentação da API

Base URL https://dualitypay.com/api/v1

HTTPS · TLS 1.3

Referência

Exemplos de Código

Introdução

A API do DualityPay permite integrar pagamentos PIX e Cartão de Crédito ao seu sistema de forma simples, segura e idempotente.

API RESTful completa

Autenticação Bearer Token

Webhooks em tempo real

Respostas JSON estruturadas

Idempotency-Key anti-duplicidade

TLS 1.3 · HMAC-SHA256

Headers Obrigatórios

Todas as requisições POST exigem:

Header	Obrigatório	Descrição
Authorization	Sim	Bearer token de autenticação
X-Client-ID	Sim	Identificador público da credencial
Idempotency-Key	Sim	Chave única por requisição (12-128 chars). UUID v4 recomendado. Válida 30 min.
Content-Type	Sim	application/json

Idempotency-Key ausente ou <12 chars → 422. Chave reutilizada em 30 min → 409 Conflict.

Obter Credenciais de API

Para usar a API, gere uma chave no painel do sistema em 3 passos.

Passo 1 — Acesse as Chaves de API

No painel, acesse "Chave API" no menu lateral.

Ir para Chaves de API

Passo 2 — Gere uma nova chave

Clique em "Gerar Nova Chave" e dê um nome descritivo.

Copie o token imediatamente — ele só é exibido uma vez.

Passo 3 — Configure no seu sistema

Seu token terá o formato:

Token

nxp_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Integração PIX

Crie pagamentos PIX e receba notificações em tempo real quando confirmados.

Endpoint

POSThttps://dualitypay.com/api/v1/payments/pix

Parâmetros do Body

Campo	Tipo	Obrigatório	Descrição
amount	float	Sim	Valor (mínimo R$ 0,01)
payer_name	string	Sim	Nome completo do pagador
payer_email	string	Sim	Email do pagador
payer_cpf	string	Sim	CPF (apenas números)
description	string	Não	Descrição do pagamento

Resposta de Sucesso 201

JSON

{
  "success": true,
  "data": {
    "transaction_uuid": "550e8400-e29b-41d4-a716-446655440000",
    "amount": 100.00,
    "fee": 4.00,
    "amount_net": 96.00,
    "status": "pending",
    "qr_code": "00020126580014BR.GOV.BCB.PIX...",
    "pix_code": "00020126580014BR.GOV.BCB.PIX...",
    "expires_at": "2024-11-26T12:30:00Z",
    "expires_in_seconds": 300
  }
}

Cashin — Depósitos via PIX

Crie depósitos PIX para adicionar saldo à conta do usuário autenticado.

Endpoint

POSThttps://dualitypay.com/api/v1/cashin/pix

Parâmetros

Campo	Tipo	Obrigatório	Descrição
amount	float	Sim	Valor (mínimo R$ 1,00)
payer_name	string	Não	Nome do pagador (usa o da conta se omitido)

Resposta de Sucesso 200

JSON

{
  "success": true,
  "transaction": {
    "uuid": "550e8400-e29b-41d4-a716-446655440000",
    "external_id": "beb1631e-8206-4c66-9cf4-775fb9d57bf0",
    "amount_gross": 10.00,
    "amount_net": 7.80,
    "fee": 2.20,
    "status": "pending",
    "expires_at": "2026-03-28T16:03:34-03:00"
  },
  "qr_code": "00020101021226940014br.gov.bcb.pix...",
  "qr_code_image_url": "https://api.qrserver.com/v1/create-qr-code/?size=300x300&data=..."
}

Cashout — Saques via PIX

Transfira saldo da conta do usuário para uma chave PIX.

Pré-requisitos para saques automáticos:

1. Credencial com modo de saque configurado como "Automático"
2. IP do servidor cadastrado nas configurações da API
3. Usuário aprovado (KYC) com saques desbloqueados

Endpoint

POSThttps://dualitypay.com/api/v1/cashout/pix

Parâmetros

Campo	Tipo	Obrigatório	Descrição
amount	float	Sim	Valor líquido desejado (mín. R$ 10,00). Taxas calculadas automaticamente.
pix_key	string	Sim	Chave PIX de destino (CPF, Email, Telefone ou Aleatória)

Resposta de Sucesso

JSON

{
  "success": true,
  "message": "Saque criado e processado automaticamente.",
  "withdrawal": {
    "id": 123,
    "amount": 95.00,
    "amount_gross": 100.00,
    "fee": 5.00,
    "status": "processing",
    "pix_key": "12345678900"
  }
}

Consultar Transações

Liste, filtre ou busque transações específicas por UUID.

Listar Transações

GEThttps://dualitypay.com/api/v1/transactions

Buscar por UUID

GEThttps://dualitypay.com/api/v1/transactions/{uuid}

Parâmetros (Query String)

Campo	Tipo	Descrição
status	string	completed · pending · failed
type	string	pix · credit
start_date	date	Data inicial (ex: 2026-01-01)
end_date	date	Data final (ex: 2026-12-31)
page	integer	Número da página
per_page	integer	Itens por página (padrão: 20)

Webhooks — Notificações

Receba notificações automáticas sempre que o status de uma transação mudar.

Configuração

Configure a URL de callback na página "Chave API" do painel, no campo "URL de Webhook".

Eventos Disparados

Evento	Descrição
transaction.completed	Transação PIX ou Cartão confirmada como paga
deposit.completed	Depósito PIX confirmado e creditado
withdrawal.completed	Saque PIX processado com sucesso

Payload (POST para sua URL)

JSON

{
  "event": "transaction.completed",
  "created_at": "2026-03-28T12:30:00Z",
  "data": {
    "transaction_uuid": "550e8400-e29b-41d4-a716-446655440000",
    "amount_gross": 100.00,
    "amount_net": 97.80,
    "fee": 2.20,
    "type": "pix",
    "gateway_provider": "pluggou",
    "external_id": "beb1631e-8206-4c66-9cf4-775fb9d57bf0",
    "created_at": "2026-03-28T12:25:00Z"
  }
}

Verificação de Assinatura HMAC-SHA256

Cada webhook inclui o header X-Webhook-Signature com HMAC-SHA256 do payload.

PHP

$payload   = file_get_contents('php://input');
$signature = $_SERVER['HTTP_X_WEBHOOK_SIGNATURE'] ?? '';
$expected  = hash_hmac('sha256', $payload, 'SEU_TOKEN_SECRET');

if (!hash_equals($expected, $signature)) {
    http_response_code(401);
    exit('Assinatura inválida');
}
// Processar evento com segurança...

Responda com HTTP 200 OK para confirmar. Caso contrário, até 3 reenvios com backoff de 60s.

Exemplo em PHP

Criação de pagamento PIX usando Guzzle HTTP.

PHP · Guzzle

<?php
$client = new \GuzzleHttp\Client();

$response = $client->post('https://dualitypay.com/api/v1/payments/pix', [
    'headers' => [
        'Authorization'   => 'Bearer SEU_TOKEN',
        'X-Client-ID'     => 'SEU_CLIENT_ID',
        'Idempotency-Key' => bin2hex(random_bytes(16)),
        'Accept'          => 'application/json',
    ],
    'json' => [
        'amount'      => 100.00,
        'payer_name'  => 'João Silva',
        'payer_email' => '[email protected]',
        'payer_cpf'   => '12345678900',
        'description' => 'Pagamento de Teste',
    ],
]);

$data = json_decode($response->getBody(), true);
echo $data['data']['pix_code']; // Exibe código PIX

Exemplo em Python

Usando a biblioteca requests.

Python · requests

import requests, uuid

response = requests.post(
    "https://dualitypay.com/api/v1/payments/pix",
    headers={
        "Authorization":   "Bearer SEU_TOKEN",
        "X-Client-ID":     "SEU_CLIENT_ID",
        "Idempotency-Key": str(uuid.uuid4()),
        "Content-Type":    "application/json",
    },
    json={
        "amount":      100.00,
        "payer_name":  "João Silva",
        "payer_email": "[email protected]",
        "payer_cpf":   "12345678900",
        "description": "Pagamento de Teste",
    },
)

data = response.json()
print(data["data"]["pix_code"])

Exemplo em JavaScript

Usando fetch nativo (Node.js 18+ ou browser).

JavaScript · fetch

const res = await fetch("https://dualitypay.com/api/v1/payments/pix", {
  method: "POST",
  headers: {
    "Authorization":   "Bearer SEU_TOKEN",
    "X-Client-ID":     "SEU_CLIENT_ID",
    "Idempotency-Key": crypto.randomUUID(),
    "Content-Type":    "application/json",
  },
  body: JSON.stringify({
    amount:      100.00,
    payer_name:  "João Silva",
    payer_email: "[email protected]",
    payer_cpf:   "12345678900",
    description: "Pagamento de Teste",
  }),
});

const data = await res.json();
console.log(data.data.pix_code);

Exemplo cURL

Shell · cURL

curl -sX POST "https://dualitypay.com/api/v1/payments/pix" \
  -H "Authorization: Bearer SEU_TOKEN" \
  -H "X-Client-ID: SEU_CLIENT_ID" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 100.00,
    "payer_name": "João Silva",
    "payer_email": "[email protected]",
    "payer_cpf": "12345678900",
    "description": "Pagamento de Teste"
  }' | jq .

Códigos de Erro HTTP

Todos os erros seguem o formato {"success":false,"code":"ERRO_CODE","message":"..."}

HTTP	Significado	Descrição
200	OK	Requisição processada com sucesso
201	Created	Recurso criado (novo pagamento)
400	Bad Request	Dados inválidos na requisição
401	Unauthorized	Token inválido ou não fornecido
403	Forbidden	Sem permissão para este recurso
404	Not Found	Transação ou recurso não encontrado
409	Conflict	Idempotency-Key duplicado nos últimos 30 min
422	Unprocessable	Validação falhou (campo inválido, key ausente)
429	Rate Limited	Muitas requisições. Aguarde e tente novamente.
500	Server Error	Erro interno. Tente novamente mais tarde.