API Skala Pay
Voltar

Documentação oficial da API pública

Esta documentação reflete o comportamento atual do sistema. Os endpoints públicos ativos são de cash-in (depósitos/cobranças Pix), cash-out (transferências/saques Pix) e webhook de adquirente. O roteamento de adquirente usa failover automático por usuário/método quando configurado no painel.

Base URL: https://skalapay.net/api Webhook base: https://skalapay.net/webhooks/acquirer/{acquirer_slug} Moeda padrão: BRL
RECURSO EXCLUSIVO • ACELERE SUA INTEGRAÇÃO

Assistente de Integração com Inteligência Artificial

Integre a Skala Pay ao seu sistema ou checkout em segundos. Copie o prompt pronto abaixo, cole na sua IA de preferência (ChatGPT, Claude, DeepSeek, Cursor, GitHub Copilot) e ela escreverá todo o código pronto e testado para a sua aplicação ou linguagem favorita.

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 Skala Pay no meu projeto.

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

## Informações Gerais
- Gateway: Skala Pay
- 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 Skala Pay.

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 Skala Pay.

A Skala Pay 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 à Skala Pay.
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 Skala Pay.

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 Skala Pay 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 Skala Pay".

Requisitos da API Skala Pay:
- 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 Skala Pay 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 assinatura de webhook e recuse payload sem assinatura válida.
  • 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.
metadata object Não Metadados livres para rastreio interno.
A resposta retorna transaction (registro interno) e acquirer_response (payload mapeado do adquirente).
Exemplo mínimo PIX
{
  "amount": 150.90,
  "payment_method": "pix",
  "description": "Recarga via PIX",
  "customer_data": {
    "name": "Joao Silva",
    "email": "[email protected]",
    "document": "12345678909",
    "phone": "11999999999"
  }
}

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
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.

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).
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
{
  "amount": 75.50,
  "payment_method": "pix",
  "pix_key": "[email protected]",
  "pix_key_type": "EMAIL",
  "description": "Pagamento de comissao"
}
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 adquirente

Endpoint público usado pelos adquirentes para atualização de status. A validação de assinatura é obrigatória (exceto integrações configuradas para ignorar assinatura em ambiente de teste).

Endpoint
POST https://skalapay.net/webhooks/acquirer/{acquirer_slug}
Header/campo lido Uso
X-SignatureAssinatura primária.
X-Veno-SignatureAssinatura VenoPag (formato t=<timestamp>,v1=<hmac>).
X-Webhook-SignatureAlternativa comum em gateways.
X-Hub-Signature / X-Hub-Signature-256Compatibilidade.
X-Efi-SignatureHeader específico da EFI.
signature / md5 no payloadFallback para integrações legadas.
Nunca confie em webhook sem assinatura válida. O endpoint retorna 401 para assinatura ausente/inválida.

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 de Assinatura HMAC
Verifique a assinatura criptográfica recebida no header X-Signature antes de autorizar a liberação do pedido na sua loja.
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.