API SkalaPay
Voltar
API v1.4 • Produção Ativa Rota Black 0 MEDs
Pacote LLM (.md) Minhas Chaves

Documentação oficial da API

Esta documentação oficial da API do SkalaPay permite integrar pagamentos instantâneos via Pix em suas aplicações, e-commerces, sistemas e bots. Crie cobranças Pix (cash-in), consulte transações, realize saques automáticos (cash-out) e receba notificações automáticas de pagamento confirmado em tempo real via Webhook (Postback).

Base URL: https://skalapay.net/api Webhooks: Notificações Automáticas (POST) Moeda padrão: BRL Liquidação Instantânea
RECURSO EXCLUSIVO • ACELERE SUA INTEGRAÇÃO COM IA

Assistente de Integração com Inteligência Artificial & LLMs

A API da SkalaPay foi desenhada para ser 100% amigável a modelos de IA. Desenvolvendo com Cursor, Claude 3.5 Sonnet, ChatGPT (GPT-4o), DeepSeek R1 ou GitHub Copilot? Use o arquivo completo em Markdown formatado especificamente para IAs ou copie o prompt mestre abaixo.

Bundle Markdown (.md) Para Agentes & IAs

Arquivo Markdown completo, estruturado modularmente para ser anexado ao contexto da sua IA ou Cursor.

Baixar .md
Padrão llms.txt Standard

Especificação internacional padrão /llms.txt na raiz para indexação direta por crawlers e IAs.

Ver llms.txt
Escolha o Modelo de Prompt:
Selecione o objetivo da integração para carregar o prompt ideal:
Prompt para IA: Integração Completa (PIX + Webhook + Saque)
Atue como um Engenheiro de Software Sênior especialista em integrações financeiras e gateways de pagamento.
Preciso integrar o gateway de pagamento SkalaPay no meu projeto.

Aqui estão as especificações técnicas da API oficial da SkalaPay:

## Informações Gerais
- Gateway: SkalaPay
- Base URL: https://skalapay.net/api
- Formato: REST JSON
- Autenticação: Toda requisição exige os seguintes Headers HTTP:
  X-Client-Id: SEU_CLIENT_ID
  X-Client-Secret: SEU_CLIENT_SECRET
  Content-Type: application/json
  Accept: application/json

## 1. Criar Cobrança PIX (Cash-In)
- Endpoint: POST https://skalapay.net/api/cash-in
- Payload JSON:
{
  "amount": 100.00,
  "payment_method": "pix",
  "description": "Pagamento Pedido #1024",
  "customer_data": {
    "name": "Nome do Cliente",
    "email": "[email protected]",
    "document": "12345678909",
    "phone": "11999999999"
  }
}
- Resposta de Sucesso (200 OK):
Retorna um JSON contendo o objeto `transaction` com `id`, `order_id`, `status` ("PENDING"), e o objeto `acquirer_response` com:
- `qr_code`: Código Pix Copia e Cola (EMV).
- `qr_code_base64`: Imagem base64 do QR Code para exibição direta em tag <img src="data:image/png;base64,..." />.
- `expires_at`: Data/hora de expiração do Pix.

## 2. Consultar Status da Transação
- Endpoint: GET https://skalapay.net/api/cash-in/{transactionId}
- Parâmetro: transactionId (id interno numérico ou order_id).
- Retorna o status atualizado da transação ("PENDING", "PROCESSING", "PAID", "FAILED", "CANCELLED", "REFUNDED", "CHARGEBACK").

## 3. Receber Webhook de Confirmação de Pagamento
- Método: POST no endpoint de webhook da minha aplicação.
- Payload recebido:
{
  "event": "cashin.confirmed",
  "status": "paid",
  "transaction_id": 1420,
  "order_id": "CASHIN_...",
  "amount": "100.00",
  "paid_at": "2026-09-29T20:00:00Z"
}
- Minha aplicação deve processar de forma idempotente, marcar o pedido como pago e retornar HTTP 200 {"received": true}.

## 4. Realizar Saque / Transferência PIX (Cash-Out)
- Endpoint: POST https://skalapay.net/api/cash-out
- Payload JSON:
{
  "amount": 50.00,
  "payment_method": "pix",
  "pix_key": "chave_pix_destino",
  "pix_key_type": "CPF", // opções: CPF, CNPJ, EMAIL, EVP
  "description": "Repasse ou Saque de Comissao"
}
- Resposta (200 OK):
{
  "success": true,
  "message": "Saque solicitado com sucesso.",
  "transaction_id": 1425,
  "balance": 850.00
}

## 5. Consultar Status do Saque
- Endpoint: GET https://skalapay.net/api/cash-out/{transactionId}

---
TAREFA:
Crie a implementação completa, limpa, tipada e com tratamento de erros na linguagem/framework do meu projeto (ex: PHP/Laravel, Node.js/Express, Python/FastAPI, etc.):
1. Uma classe/serviço cliente HTTP `SkalaPayService` encapsulando as chamadas com timeout, headers e tratamento de exceções.
2. Um exemplo de controller/rota criando a cobrança Pix e retornando o QR Code para o frontend.
3. Um controller de Webhook recebendo a confirmação e aprovando o pedido com segurança.
4. Exemplo de chamada para realizar saque PIX.
5. Indique onde colocar as credenciais no arquivo .env.
Prompt para IA: Apenas Cobrança Pix e Consulta
Atue como um Engenheiro de Software Sênior.
Preciso integrar no meu backend a geração de cobranças PIX dinâmicas e verificação de status via gateway SkalaPay.

Especificações:
- Base URL: https://skalapay.net/api
- Headers obrigatórios:
  X-Client-Id: SEU_CLIENT_ID
  X-Client-Secret: SEU_CLIENT_SECRET
  Content-Type: application/json
  Accept: application/json

1. Endpoint de Criação: POST https://skalapay.net/api/cash-in
Payload:
{
  "amount": 29.90,
  "payment_method": "pix",
  "description": "Assinatura Mensal",
  "customer_data": {
    "name": "Maria Oliveira",
    "email": "[email protected]",
    "document": "12345678909",
    "phone": "11988887777"
  }
}
Retorno de Sucesso:
Retorna `qr_code` (código copia e cola) e `qr_code_base64` (imagem em base64 pronta para renderizar).

2. Endpoint de Consulta de Status: GET https://skalapay.net/api/cash-in/{transactionId}
Retorna o status atual ("PENDING", "PROCESSING", "PAID", "FAILED", etc).

TAREFA:
Crie um módulo ou serviço na minha stack que gere a cobrança, salve o identificador no banco de dados e forneça um endpoint para o frontend renderizar o QR code e fazer polling de status a cada 3 segundos até que o status seja PAID.
Prompt para IA: Recepção de Webhook
Atue como um Desenvolvedor Backend Sênior.
Preciso criar uma rota de Webhook para receber notificações de pagamentos aprovados da SkalaPay.

A SkalaPay dispara um POST com o seguinte formato JSON:
{
  "event": "cashin.confirmed",
  "status": "paid",
  "transaction_id": 9845,
  "order_id": "CASHIN_66a123...",
  "amount": "150.00",
  "paid_at": "2026-09-29T21:00:00Z"
}

TAREFA:
Crie um controller de webhook profissional que:
1. Receba a requisição POST e faça o parse do JSON.
2. Valide se `status === 'paid'` ou `status === 'confirmed'` ou `event === 'cashin.confirmed'`.
3. Busque a transação/pedido no banco de dados local pelo `order_id` ou `transaction_id`.
4. Garanta idempotência: se o pedido já estiver marcado como pago, não processe a entrega duas vezes.
5. Se ainda estiver pendente, marque como pago, grave a data de pagamento e execute a liberação do pedido.
6. Retorne status HTTP 200 {"received": true} para confirmar o recebimento à SkalaPay.
7. Trate erros em bloco try/catch com logging adequado.
Prompt para IA: Saques Automáticos PIX (Cash-Out)
Atue como um Engenheiro Backend Sênior.
Preciso integrar saques instantâneos via PIX na minha aplicação utilizando a API SkalaPay.

Especificações:
- Base URL: https://skalapay.net/api
- Headers:
  X-Client-Id: SEU_CLIENT_ID
  X-Client-Secret: SEU_CLIENT_SECRET
  Content-Type: application/json
  Accept: application/json

Endpoint de Saque: POST https://skalapay.net/api/cash-out
Payload JSON:
{
  "amount": 100.00,
  "payment_method": "pix",
  "pix_key": "12345678909",
  "pix_key_type": "CPF", // Opções: "CPF", "CNPJ", "EMAIL", "EVP" (chave aleatória)
  "description": "Pagamento de Comissao #45"
}

Resposta (200 OK):
{
  "success": true,
  "message": "Saque solicitado com sucesso.",
  "transaction_id": 1420,
  "balance": 924.50
}

Endpoint de Consulta de Saque: GET https://skalapay.net/api/cash-out/{transactionId}

TAREFA:
Crie um serviço de saque Pix seguro que valide o saldo interno do usuário antes de solicitar, chame a API SkalaPay com idempotency key única, capture o `transaction_id` retornado e trate erros como saldo insuficiente (422) ou limites de saque com mensagens claras.
Prompt para IA: Plugin WordPress / WooCommerce
Atue como um Desenvolvedor WordPress / WooCommerce Especialista em Gateways de Pagamento.
Preciso de um plugin customizado para WooCommerce que adicione o método de pagamento "PIX SkalaPay".

Requisitos da API SkalaPay:
- Base URL: https://skalapay.net/api
- Headers:
  X-Client-Id: configurável nas opções do plugin
  X-Client-Secret: configurável nas opções do plugin
  Content-Type: application/json

Fluxo do Plugin:
1. No checkout do WooCommerce, exibir a opção "PIX - Pagamento Instantâneo".
2. Ao finalizar o pedido:
   - Chamar POST https://skalapay.net/api/cash-in passando o total do pedido, dados do cliente e order_id do WooCommerce.
   - Redirecionar para a página de "Obrigado" exibindo o QR Code (base64) e o código Pix Copia e Cola com botão de cópia fácil.
3. Registrar um endpoint REST no WordPress `/wp-json/skalapay/v1/webhook` para receber o webhook de pagamento aprovado da SkalaPay e atualizar o pedido do WooCommerce para "Concluído" (completed) ou "Processando" (processing) automaticamente.

TAREFA:
Gere o código completo do plugin `skalapay-pix-for-woocommerce.php` pronto para ser instalado na pasta wp-content/plugins.

Segurança obrigatória

Antes de ir para produção, valide estes pontos:

  • Use HTTPS em toda chamada e nunca exponha client_secret no frontend/browser.
  • Restrinja IPs permitidos da integração no painel (whitelist).
  • Guarde credenciais em variável de ambiente/cofre, nunca em código fonte.
  • Valide os campos order_id e status PAID no webhook antes de liberar o saldo ao cliente.
  • Monitore respostas 401, 429 e 503 para contingência.
O middleware bloqueia a credencial por 15 minutos após 5 tentativas de segredo inválido.

Autenticação

As rotas /api/cash-in aceitam credencial de integração via header ou Basic Auth. Se o usuário já estiver logado por sessão, o mesmo middleware também aplica validação de IP.

Opção A: headers X-Client
Headers
Content-Type: application/json
Accept: application/json
X-Client-Id: seu_client_id
X-Client-Secret: seu_client_secret
Opção B: Basic Auth
Header Authorization
Authorization: Basic base64(seu_client_id:seu_client_secret)
Accept: application/json
Não existe fluxo OAuth público em /oauth/token. A autenticação oficial da API é via chave de integração.

POST /api/cash-in

Cria uma transação de entrada e processa no adquirente elegível.

Endpoint
POST https://skalapay.net/api/cash-in
Campo Tipo Obrigatório Observação
amount number Sim Valor entre 0.01 e 100000.
payment_method string Sim pix, boleto, credit_card, debit_card, crypto.
payment_acquirer_id integer Não Preferência de adquirente. Se indisponível/inválido, o sistema usa failover.
description string Não Texto livre (máx. 255).
integration_key_id integer Não Opcional; quando omitido, o middleware usa a credencial autenticada.
customer_data object Sim Dados do pagador.
customer_data.name string Sim Nome completo.
customer_data.email string Sim Email válido.
customer_data.document string Sim CPF/CNPJ.
customer_data.phone string Não Telefone do cliente.
payment_data object Não Campos específicos por método/adquirente (detalhes abaixo).
split_rules array Não Opcional. Regras de split (em %) para dividir o recebimento entre múltiplos recebedores. O formato do item pode variar por adquirente.
split array Não Alias alternativo de split_rules. O backend normaliza os dois formatos.
postback_url string (URL) Não URL do seu servidor para onde o SkalaPay enviará o webhook automático quando o pagamento for aprovado (status PAID). Se omitido, utiliza a URL de Webhook cadastrada no seu painel.
metadata object Não Metadados livres para rastreio interno.
A resposta retorna transaction (registro interno com QR Code e Copia e Cola) e acquirer_response (payload do adquirente).
Exemplo de Criação PIX com Webhook
{
  "amount": 150.90,
  "payment_method": "pix",
  "description": "Pedido #1042 - Recarga via PIX",
  "postback_url": "https://seusite.com/api/webhook-skalapay",
  "customer_data": {
    "name": "Joao Silva",
    "email": "[email protected]",
    "document": "12345678909",
    "phone": "11999999999"
  }
}
RECORRÊNCIA NATIVA

POST /subscriptions — Pix Automático & Assinaturas

Permite criar cobranças recorrentes e planos de assinatura com débitos programados via Pix Automático. Ideal para SaaS, assinaturas de conteúdo e mensalidades.

POST https://skalapay.net/api/subscriptions
Campo Tipo Obrigatório Descrição
plan_id string Sim Identificador do plano ou nome da assinatura.
amount numeric Sim Valor da mensalidade/período em Reais (BRL). Ex.: 49.90.
interval string Sim Intervalo da recorrência: MONTHLY (mensal), WEEKLY (semanal), YEARLY (anual).
customer_data object Sim Dados do assinante (name, email, document, phone).
postback_url string (URL) Não URL para receber avisos a cada renovação de ciclo (subscription.charged, subscription.cancelled).
Exemplo de Criação de Assinatura
{
  "plan_id": "pro_monthly",
  "amount": 59.90,
  "interval": "MONTHLY",
  "customer_data": {
    "name": "Mariana Souza",
    "email": "[email protected]",
    "document": "98765432100",
    "phone": "11987654321"
  },
  "postback_url": "https://seusite.com/api/webhooks/assinaturas"
}

PIX, boleto, cartão e crypto

O método aceito depende do adquirente ativo para o usuário e da configuração em admin. Matriz atual por integração nativa:

Adquirente (slug) PIX Boleto Cartão Crypto
kokupay_black Rota Black Sim Não Não Não
cajupay_black Rota 0 MED Sim Não Não Não
cajupay (White) Sim Não Não Não
pagsmile Nominal Limpo Sim Sim Não Não
voltpay Sim Não Não Não
voltpay_black Sim Não Não Não
medusapayments Sim Não Não Não
pushinpay Sim Sim Não Não
efi Sim Sim Sim (credit_card/debit_card) Não
facilitapay Sim Sim Não Sim
mystick Sim Não Não Não
woopi Sim Não Não Não
suitpay Sim Sim Sim (credit_card/debit_card) Não
vulcapay Sim Não Não Não
bspay Sim Não Não Não
pixup Sim Não Não Não

Exemplos práticos de payment_data por método:

Boleto (exemplo completo para PushInPay)
{
  "amount": 250.00,
  "payment_method": "boleto",
  "customer_data": {
    "name": "Maria Souza",
    "email": "[email protected]",
    "document": "12345678909",
    "phone": "11988887777"
  },
  "payment_data": {
    "boleto": {
      "due_date": "2026-03-15",
      "payer_address_zipcode": "01310100",
      "payer_address_public_place": "Av Paulista",
      "payer_address_neighborhood": "Bela Vista",
      "payer_address_number": "1000",
      "payer_address_city": "Sao Paulo",
      "payer_address_state": "SP"
    }
  }
}
Cartão (EFI)
{
  "amount": 89.90,
  "payment_method": "credit_card",
  "customer_data": {
    "name": "Cliente Cartao",
    "email": "[email protected]",
    "document": "12345678909",
    "phone": "11977776666"
  },
  "payment_data": {
    "payment_token": "tok_xxxxxxxxx",
    "installments": 1,
    "billing_address": {
      "street": "Rua A",
      "number": "123",
      "neighborhood": "Centro",
      "zipcode": "01001000",
      "city": "Sao Paulo",
      "state": "SP"
    }
  }
}
Crypto cash-in (FacilitaPay)
{
  "amount": 500.00,
  "payment_method": "crypto",
  "customer_data": {
    "name": "Cliente Crypto",
    "email": "[email protected]",
    "document": "12345678909"
  },
  "payment_data": {
    "subject_id": "SEU_SUBJECT_ID",
    "from_bank_account_id": "UUID_ORIGEM",
    "to_bank_account_id": "UUID_DESTINO",
    "currency": "BRL",
    "exchange_currency": "USD"
  }
}
Campos exatos podem variar por adquirente. Em caso de 422, valide o corpo retornado em messages ou error.

Split

Para dividir o valor do pagamento entre múltiplos recebedores, envie split_rules (ou split). Cada item define o usuário/recebedor e o percentual (%).

  • A soma dos percentuais deve ser ≤ 100.
  • O restante (se houver) normalmente fica com o recebedor principal (depende do adquirente).
  • Campos do item podem variar por adquirente (ex.: recipient_id).
Exemplo de requisição com split_rules
{
  "amount": 1000.00,
  "payment_method": "pix",
  "customer_data": {
    "name": "Pagador Split",
    "email": "[email protected]",
    "document": "12345678909"
  },
  "split_rules": [
    {
      "recipient_id": "SUBCONTA_A",
      "percentage": 70
    },
    {
      "recipient_id": "SUBCONTA_B",
      "percentage": 30
    }
  ]
}
Você pode usar split como alias de split_rules.
MECANISMO BACEN & CONTESTAÇÕES

MED Bacen & Gestão de Contestações

O Mecanismo Especial de Devolução (MED) foi instituído pela Resolução BCB nº 103/2021 para viabilizar devoluções de valores em casos de fundada suspeita de fraude ou erro operacional. No SkalaPay, você conta com rotas blindadas (Rota Black com zero alertas indevidos) e infraestrutura completa para notificação instantânea e envio de defesa com evidências em conformidade com o Banco Central.

Rota Black 0 MED: Clientes configurados com adquirentes blindadas (ex.: CajuPay Black e Pagsmile Nominal Limpo) operam com camadas anti-fraude reforçadas, reduzindo a zero os falsos positivos de contestação e MEDs fraudulentos de má-fé.

Fluxo Operacional de MED

1 Notícia de Infração

Recebimento imediato via Webhook com ID do MED, valor e dados do cliente contestante.

2 Prazo Bacen (7 dias)

Tempo regulamentar para reunir logs de IP, dados cadastrais e comprovantes de entrega do serviço.

3 Envio de Defesa

Submissão direta pelo painel ou via API com links de comprovantes e laudo técnico.

4 Parecer & Desbloqueio

Após validação bancária, saldo retido cautelarmente é desbloqueado integralmente.

Webhook: Notificação de Notícia de Infração (MED)
{
  "event": "pix.med_created",
  "data": {
    "med_id": "med_892019401",
    "transaction_id": "tx_caju_black_182940",
    "external_id": "e2e_E0003816620241027150000",
    "amount": 420.50,
    "dispute_type": "fraud_allegation",
    "status": "under_analysis",
    "deadline_at": "2026-11-03T18:00:00Z",
    "payer": {
      "name": "Cliente Contestante",
      "document": "12345678909",
      "bank": "Banco Santander (Brasil) S.A."
    }
  }
}
POST https://skalapay.net/api/meds/{id}/defense
Exemplo de Envio de Defesa Técnica de MED
{
  "defense_summary": "Produto digital entregue instantaneamente com comprovante de login e IP correspondente ao cliente.",
  "delivery_proof_url": "https://meustorage.com/comprovantes/pedido-1042-entrega.pdf",
  "customer_ip": "189.40.12.88",
  "customer_email": "[email protected]",
  "logs": [
    "2026-10-27 14:30:10 - Pedido criado no checkout",
    "2026-10-27 14:30:45 - Pix confirmado via webhook",
    "2026-10-27 14:31:02 - Acesso liberado à plataforma e senha gerada",
    "2026-10-27 14:35:18 - Download do produto realizado pelo IP 189.40.12.88"
  ]
}
Atenção ao Prazo Bacen: Defesas submetidas após o prazo expiram compulsoriamente pelo regulamento do Bacen. Mantenha os webhooks de MED sempre ativos em sua URL de Postback.

GET /api/cash-in

Lista as transações de cash-in da credencial autenticada, com paginação.

Endpoint
GET https://skalapay.net/api/cash-in
Query param Tipo Descrição
statusstringFiltra por status (PENDING, PAID, etc).
payment_methodstringFiltra por método.
date_fromYYYY-MM-DDData inicial (inclusive).
date_toYYYY-MM-DDData final (inclusive).
min_amountnumberValor mínimo.
max_amountnumberValor máximo.
per_pageintegerTamanho da página (máximo 100, padrão 20).
Exemplo de resposta
{
  "success": true,
  "data": {
    "transactions": [
      {
        "id": 1532,
        "order_id": "CASHIN_67ac56f3ca69f_1739446313",
        "status": "PAID",
        "amount": "150.90",
        "payment_method": "PIX"
      }
    ],
    "pagination": {
      "current_page": 1,
      "per_page": 20,
      "total": 1,
      "last_page": 1,
      "has_more": false
    }
  }
}

GET /api/cash-in/{transactionId}

Consulta uma transação por order_id ou por id numérico.

Endpoint
GET https://skalapay.net/api/cash-in/{transactionId}
Se a transação estiver PENDING ou PROCESSING, o backend consulta o adquirente para atualizar status na hora.

POST /api/cash-out

Realiza um saque ou transferência instantânea via PIX debitando diretamente do saldo disponível da conta na SkalaPay. O envio é roteado automaticamente com failover inteligente entre as adquirentes ativas (ex: VenoPag).

Endpoint
POST https://skalapay.net/api/cash-out
Campo Tipo Obrigatório Observação
amount number Sim Valor do saque em reais (ex: 50.00). Mínimo 0.01.
payment_method string Não Método de liquidação. Padrão: pix.
pix_key string Sim Chave PIX de destino (CPF, CNPJ, E-mail ou Chave Aleatória/EVP).
pix_key_type string Não Tipo da chave: CPF, CNPJ, EMAIL, EVP. Se omitido, o sistema detecta automaticamente.
description string Não Descrição ou motivo do pagamento (máx. 255 caracteres).
postback_url string (URL) Não URL para receber webhook automático quando a transferência for confirmada (cashout.paid) ou falhar (cashout.failed). Se omitido, utiliza a URL de Webhook cadastrada no seu painel.
Autenticação via API: Chamadas autenticadas com X-Client-Id e X-Client-Secret não exigem envio de PIN. Para saques via PIX com chave CPF/CNPJ, certifique-se de que o documento da conta ou da chave seja válido.
Exemplo de Requisição PIX com Webhook
{
  "amount": 75.50,
  "payment_method": "pix",
  "pix_key": "[email protected]",
  "pix_key_type": "EMAIL",
  "description": "Pagamento de comissao #502",
  "postback_url": "https://seusite.com/api/webhook-skalapay"
}
Exemplo de Resposta (200 OK)
{
  "success": true,
  "message": "Saque solicitado com sucesso.",
  "transaction_id": 1420,
  "balance": 924.50
}

GET /api/cash-out/{transactionId}

Consulta o status de um saque ou transferência em tempo real pelo transaction_id ou order_id.

Endpoint
GET https://skalapay.net/api/cash-out/{transactionId}
Caso o saque esteja em processamento na adquirente, a API sincroniza o status em tempo real com a adquirente e retorna os dados atualizados.

Webhook de Notificação (Postback Automático)

O SkalaPay envia requisições HTTP POST em tempo real para o seu servidor assim que um pagamento via Pix for confirmado ou alterar de status. A entrega do webhook é 100% automática e ocorre em milissegundos após a compensação bancária.

1. Dinâmico via API (Recomendado)

Envie o campo postback_url no corpo da requisição ao criar o Pix em POST /api/cash-in. O webhook daquela transação será enviado automaticamente para a URL informada.

2. Configurado no Painel (Opcional)

No painel em Credenciais de API, configure a URL de Webhook padrão da sua chave. Qualquer cobrança gerada que não passar URL própria usará essa URL automaticamente.

Eventos de Webhook

Evento (event) Quando ocorre Status da transação
transaction.paid Disparado instantaneamente quando o cliente final realiza o pagamento do Pix.
transaction.created Disparado quando a cobrança Pix é gerada com QR Code e Copia e Cola. PENDING
cashout.paid Disparado quando uma transferência / saque Pix via API é liquidada com sucesso.
cashout.failed Disparado se uma transferência / saque Pix falhar ou for recusada pelo banco. FAILED

Payload enviado pelo SkalaPay (Exemplo: transaction.paid)

Quando o pagamento for confirmado, seu servidor receberá um POST com Content-Type: application/json contendo o seguinte corpo:

JSON recebido no seu servidor (POST)
{
  "event": "transaction.paid",
  "transaction_id": 1542,
  "external_id": "pix_c3f892a014902b489",
  "order_id": "CASHIN_67b8_1740000000",
  "type": "CASH_IN",
  "status": "PAID",
  "amount": 100.00,
  "net_amount": 93.00,
  "fee": 7.00,
  "payment_method": "pix",
  "payer": {
    "name": "João da Silva",
    "document": "12345678901",
    "email": "[email protected]",
    "phone": "11999999999"
  },
  "paid_at": "2026-10-02T21:40:00.000Z",
  "created_at": "2026-10-02T21:38:00.000Z"
}
Campo Tipo Descrição
eventstringNome do evento disparado (ex: transaction.paid).
transaction_idintegerID único da transação na SkalaPay.
order_idstringIdentificador da cobrança para conciliação no seu sistema.
statusstringStatus do pagamento (PAID para aprovado).
amountfloatValor bruto da transação paga pelo cliente em reais.
net_amountfloatValor líquido creditado na sua carteira após dedução das taxas.
feefloatTaxa do gateway descontada da transação.
payerobjectDados cadastrais do cliente pagador (nome, documento, email, telefone).
paid_atstring (ISO-8601)Data e horário da confirmação do pagamento.

Como responder ao Webhook

Regra de Confirmação: Seu servidor deve responder com status HTTP 200 OK e tempo de resposta inferior a 5 segundos. Isso confirma o recebimento do webhook e encerra o ciclo de notificação.
Exemplo em PHP
{"error":"Invalid event"}
Exemplo em Node.js (Express)
app.post('/webhook-skalapay', (req, res) => {
  const { event, status, order_id, amount } = req.body;

  if (event === 'transaction.paid' && status === 'PAID') {
    // Liberar pedido ou saldo no seu banco...
    console.log(`Pagamento aprovado: Pedido ${order_id} - R$ ${amount}`);
  }

  return res.status(200).json({ received: true });
});

Status e Erros da API

A API segue as convenções HTTP para reportar sucessos e falhas. Todas as respostas de erro retornam um objeto JSON estruturado com código de erro, mensagem amigável e detalhes de validação por campo.

Ciclo de Vida e Status da Transação

Cada transação passa por estados bem definidos durante seu ciclo de vida. O status atualizado é enviado via Webhook e retornado no endpoint de consulta:

PENDING Aguardando Pagamento
Transação gerada com sucesso. O QR Code PIX, código de barras ou link de checkout está ativo e aguardando liquidação pelo pagador.
PROCESSING Em Processamento
O pagamento foi iniciado e está em análise pelo gateway, adquirente ou sistema antifraude. Aguarde a confirmação final.
Aprovada / Paga
Transação confirmada e compensada! O saldo líquido foi disponibilizado na carteira e a notificação de webhook foi disparada.
FAILED Recusada / Falha
Transação rejeitada pelo emissor (ex: saldo insuficiente, bloqueio de segurança ou antifraude). Nenhuma cobrança foi efetivada.
CANCELLED Cancelada
O pagamento expirou por tempo limite (timeout de PIX) ou foi cancelado manualmente antes da compensação.
REFUNDED Estornada / Devolvida
O valor pago foi devolvido parcial ou integralmente à conta de origem do comprador via estorno ou resolução de disputa.

Formato Padrão de Resposta de Erro (JSON)

Exemplo de Payload de Erro 422
{
  "status": "error",
  "message": "Os dados fornecidos são inválidos.",
  "errors": {
    "amount": [
      "O campo valor é obrigatório e deve ser no mínimo 0.01."
    ],
    "payment_method": [
      "O método informado é inválido ou está desabilitado."
    ],
    "customer_data.document": [
      "CPF ou CNPJ inválido."
    ]
  },
  "code": 422
}

Tabela Completa de Códigos HTTP

HTTP Quando acontece Ação recomendada
200 OK Consulta ou listagem executada com sucesso. Processar o JSON de resposta normalmente.
201 Created Cash-in criado com sucesso e processado no gateway. Salvar order_id e aguardar webhook de liquidação.
400 Bad Request JSON malformatado ou cabeçalhos ausentes. Validar sintaxe do payload e cabeçalho Content-Type: application/json.
401 Unauthorized Credencial inválida, expirada ou segredo incorreto. Verificar X-Client-Id e X-Client-Secret no painel de API.
403 Forbidden IP do servidor chamador não consta na Whitelist. Adicionar o endereço IP público do servidor na aba Whitelist de IPs.
404 Not Found Transação ou recurso não encontrado para o ID fornecido. Conferir o código identificador enviado na URL de consulta.
422 Unprocessable Validação de campos, regras de split ou valor inválido. Corrigir os campos detalhados no nó errors retornado.
429 Rate Limit Limite de requisições por minuto excedido (proteção anti-abuso). Respeitar o header Retry-After e aplicar retentativa exponencial.
500 Internal Error Falha não tratada no processamento interno do servidor. Notificar o suporte técnico informando o horário e payload da requisição.
503 Unavailable Adquirentes temporariamente indisponíveis no momento. O sistema aciona failover automático. Tente novamente com backoff.
Dica de Integração: Para garantir alta disponibilidade, utilize sempre filas assíncronas (ex: RabbitMQ, Redis Queue) para consumir webhooks e evite bloquear a resposta HTTP.

Checklist de Produção & Go-Live

Antes de iniciar o processamento real de pagamentos em larga escala, siga este checklist estruturado para garantir que a sua integração opere com segurança máxima, alta performance e sem interrupções.

Checklist de Homologação Obrigatório

1. Chaves de Produção Oficiais
Gere o par de credenciais Client ID e Client Secret. Guarde o segredo em cofre de variáveis de ambiente do seu servidor.
2. Whitelist de IPs dos Servidores
Cadastre todos os IPs públicos de saída da sua aplicação no painel para evitar bloqueio por HTTP 403 Forbidden.
3. Webhook com HTTPS & SSL Válido
O endpoint configurado para receber notificações deve obrigatoriamente possuir certificado SSL ativo (HTTPS) e responder com status 200 OK.
4. Validação & Conciliação Direta
Valide os campos order_id e status: 'PAID' no payload do webhook antes de liberar o pedido na sua loja. A confirmação é instantânea e simplificada.
5. Retentativas & Backoff Exponencial
Trate instabilidades de rede com retentativas espaçadas (1s, 2s, 4s, 8s) para códigos transitórios como 429 e 503.
6. Teste de Fluxo Ponta a Ponta
Execute um PIX real de teste (ex: R$ 1,00), pague pelo app do seu banco e confirme a transição para PAID via webhook.

Exemplo de Chamada de Produção (cURL)

cURL de Validação de Produção (PIX)
curl -X POST 'https://skalapay.net/api/cash-in' \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'X-Client-Id: seu_client_id_producao' \
  -H 'X-Client-Secret: seu_client_secret_producao' \
  -d '{
    "amount": 1.00,
    "payment_method": "pix",
    "description": "Teste de Homologação Go-Live",
    "customer_data": {
      "name": "Cliente Teste",
      "email": "[email protected]",
      "document": "12345678909"
    }
  }'
Pronto para Vender: Concluídas as etapas acima, sua conta está 100% pronta para transacionar em produção com conciliação automática e failover de alta resiliência.