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).
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.
Arquivo Markdown completo, estruturado modularmente para ser anexado ao contexto da sua IA ou Cursor.
Especificação internacional padrão /llms.txt na raiz para indexação direta por crawlers e IAs.
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.
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.
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.
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.
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_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 os campos
order_ide statusPAIDno webhook antes de liberar o saldo ao cliente. - 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. |
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. |
transaction (registro interno com QR Code e Copia e Cola) e acquirer_response (payload do adquirente).
{
"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"
}
}
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.
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). |
{
"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:
{
"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.
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.
Fluxo Operacional de MED
Recebimento imediato via Webhook com ID do MED, valor e dados do cliente contestante.
Tempo regulamentar para reunir logs de IP, dados cadastrais e comprovantes de entrega do serviço.
Submissão direta pelo painel ou via API com links de comprovantes e laudo técnico.
Após validação bancária, saldo retido cautelarmente é desbloqueado integralmente.
{
"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."
}
}
}
https://skalapay.net/api/meds/{id}/defense
{
"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"
]
}
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). |
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. |
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 #502",
"postback_url": "https://seusite.com/api/webhook-skalapay"
}
{
"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 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.
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.
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. | PAID |
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. | PAID |
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:
{
"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 |
|---|---|---|
event | string | Nome do evento disparado (ex: transaction.paid). |
transaction_id | integer | ID único da transação na SkalaPay. |
order_id | string | Identificador da cobrança para conciliação no seu sistema. |
status | string | Status do pagamento (PAID para aprovado). |
amount | float | Valor bruto da transação paga pelo cliente em reais. |
net_amount | float | Valor líquido creditado na sua carteira após dedução das taxas. |
fee | float | Taxa do gateway descontada da transação. |
payer | object | Dados cadastrais do cliente pagador (nome, documento, email, telefone). |
paid_at | string (ISO-8601) | Data e horário da confirmação do pagamento. |
Como responder ao Webhook
200 OK e tempo de resposta inferior a 5 segundos. Isso confirma o recebimento do webhook e encerra o ciclo de notificação.
{"error":"Invalid event"}
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:
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.
order_id e status: 'PAID' no payload do webhook antes de liberar o pedido na sua loja. A confirmação é instantânea e simplificada.
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"
}
}'