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.
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.
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.
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.
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.
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.
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_secretno 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,429e503para contingência.
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.
Content-Type: application/json Accept: application/json X-Client-Id: seu_client_id X-Client-Secret: seu_client_secret
Authorization: Basic base64(seu_client_id:seu_client_secret) Accept: application/json
/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.
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. |
transaction (registro interno) e acquirer_response (payload mapeado do adquirente).
{
"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:
{
"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"
}
}
}
{
"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"
}
}
}
{
"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"
}
}
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).
{
"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
}
]
}
split como alias de split_rules.
GET /api/cash-in
Lista as transações de cash-in da credencial autenticada, com paginação.
GET https://skalapay.net/api/cash-in
| Query param | Tipo | Descrição |
|---|---|---|
status | string | Filtra por status (PENDING, PAID, etc). |
payment_method | string | Filtra por método. |
date_from | YYYY-MM-DD | Data inicial (inclusive). |
date_to | YYYY-MM-DD | Data final (inclusive). |
min_amount | number | Valor mínimo. |
max_amount | number | Valor máximo. |
per_page | integer | Tamanho da página (máximo 100, padrão 20). |
{
"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.
GET https://skalapay.net/api/cash-in/{transactionId}
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).
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). |
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.
{
"amount": 75.50,
"payment_method": "pix",
"pix_key": "[email protected]",
"pix_key_type": "EMAIL",
"description": "Pagamento de comissao"
}
{
"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.
GET https://skalapay.net/api/cash-out/{transactionId}
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).
POST https://skalapay.net/webhooks/acquirer/{acquirer_slug}
| Header/campo lido | Uso |
|---|---|
X-Signature | Assinatura primária. |
X-Veno-Signature | Assinatura VenoPag (formato t=<timestamp>,v1=<hmac>). |
X-Webhook-Signature | Alternativa comum em gateways. |
X-Hub-Signature / X-Hub-Signature-256 | Compatibilidade. |
X-Efi-Signature | Header específico da EFI. |
signature / md5 no payload | Fallback para integrações legadas. |
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:
Formato Padrão de Resposta de Erro (JSON)
{
"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. |
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
Client ID e Client Secret. Guarde o segredo em cofre de variáveis de ambiente do seu servidor.
403 Forbidden.
200 OK.
X-Signature antes de autorizar a liberação do pedido na sua loja.
429 e 503.
PAID via webhook.
Exemplo de Chamada de Produção (cURL)
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"
}
}'