Documentação — NextPay

API de Integração

Integre com seu Client ID e Client Secret para criar cobranças (cash in), solicitar saques (cash out) e consultar status. Opcionalmente, informe um webhook_url para ser notificado automaticamente.

Dica: gere sua chave em Dashboard → API, com as permissões necessárias.

URL Base

https://www.paguipay.com

Autenticação

Envie credenciais via cabeçalhos ou Basic Auth.

Headers

X-Client-Id: np_xxx
X-Client-Secret: npsec_xxx

Basic Auth

Authorization: Basic base64(ClientID:ClientSecret)

Criar Cash In

POST /api/requests?route=api-cashin-create

Body

{
  "amount": 123.45,
  "name": "Cliente Pix",
  "document": "12345678900",
  "description": "Pedido #123",
  "webhook_url": "https://seusistema.com/webhooks/nextpay",
  "splits": [
    {
      "username": "usuario1",
      "percentage": 10
    },
    {
      "username": "usuario2",
      "percentage": 5
    }
  ]
}

Nota: O campo splits é opcional e permite múltiplas divisões de valor. A soma das porcentagens não pode ultrapassar 100%.

Resposta

{
  "ok": true,
  "qr_img": "data:image/png;base64,...",
  "copyPaste": "000201...",
  "code": "...",
  "request_number": "vp_...",
  "transaction_id": "..."
}

Consultar Status

GET /api/requests?route=api-cashin-status&request_number=vp_...

Resposta

{ "ok": true, "status": "pending|confirmed|expired" }

Solicitar Cash Out

POST /api/requests?route=api-cashout-create

Requisitos: a chave deve possuir permissão cashout, a requisição deve vir de um endereço IPv4 e o IP precisa estar configurado em IP da chave. Caso contrário, a resposta será IP não permitido.

PIX_TYPE aceitos

EMAIL
CPF
CNPJ
PHONE
EVP

Body

{
  "amount": 250.00,
  "name": "Fulano de Tal",
  "document": "00000000000",
  "pix_key": "fulano@banco.com",
  "pix_type": "EMAIL",
  "webhook_url": "https://seusistema.com/webhooks/nextpay"
}

Formatação: para CPF/CNPJ envie apenas dígitos (sem pontos/traços); para PHONE use E.164 (+5511999999999) ou apenas dígitos com DDI+DDD; EMAIL deve ser um email válido; EVP pode ser chave aleatória (32 hex) ou UUID.

Resposta

{ "ok": true, "e2e": "WD_...", "amount": 250, "fee": 2.5, "status": "pending" }

Webhooks

Enviaremos POST para seu webhook_url quando houver mudança de status.

Cash In

{ "type":"cashin", "status":"confirmed", "amount":123.45, "fee":1.23, "request_number":"vp_...", "transaction_id":"...", "e2e":"", "provider":"versellpay", "updated_at":"2025-11-24 12:00:00" }

Cash Out

{ "type":"cashout", "status":"completed", "amount":250.00, "fee":2.50, "transaction_id":"...", "e2e":"WD_...", "updated_at":"2025-11-24 12:00:00" }

Permissões

Configure na chave as permissões necessárias: cashin, cashout, balance.

Exemplos

Cash In (cURL)

curl -X POST "https://SEU_DOMINIO/api/requests?route=api-cashin-create" \
 -H "X-Client-Id: np_xxx" -H "X-Client-Secret: npsec_xxx" \
 -H "Content-Type: application/json" \
 -d '{"amount": 123.45, "webhook_url": "https://seusistema.com/webhooks/nextpay"}'

Cash Out (cURL)

curl -X POST "https://SEU_DOMINIO/api/requests?route=api-cashout-create" \
 -H "Authorization: Basic BASE64" -H "Content-Type: application/json" \
 -d '{"amount": 250, "name":"Fulano", "document":"00000000000", "pix_key":"fulano@banco.com", "pix_type":"email"}'

Status (cURL)

curl -X GET "https://SEU_DOMINIO/api/requests?route=api-cashin-status&request_number=vp_..." \
 -H "X-Client-Id: np_xxx" -H "X-Client-Secret: npsec_xxx"