API de Pagamentos

Bem-vindo à documentação completa da nossa API de pagamentos. Esta API permite que você integre facilmente soluções de pagamento em seu aplicativo ou site, processando transações via PIX e gerenciando cashouts.

Início Rápido

Para começar a usar nossa API de pagamentos, você precisará:

  1. Obter suas credenciais de API no painel administrativo
  2. Configurar a autenticação em suas requisições
  3. Implementar o endpoint de webhook para receber atualizações

URL Base da API

Todas as requisições devem ser feitas para o seguinte domínio base:

BASE https://api.spedpay.com.br
Importante Todos os endpoints documentados devem ser anexados a esta URL base. Por exemplo, para criar uma transação, você deve fazer uma requisição para https://api.spedpay.com.br/v1/transactions.

Autenticação

A autenticação é feita através do API Secret nos cabeçalhos da requisição:

Cabeçalho de Autenticação 
api-secret: SEU_API_SECRET
Nota Você pode obter seu API Secret na seção integrações -> API de pagamentos do painel da sua conta.

Consultar informações da conta

Este endpoint permite consultar as informações da vinculada a chave de API.

GET https://api.spedpay.com.br/v1/account-info

Resposta

JSON Response 
{
"email": "jonhdoe@email.com",
"name": "Jonh doe",
"document": "12345678912",
}

Consultar Transação

Este endpoint permite consultar os detalhes de uma transação previamente criada.

GET https://api.spedpay.com.br/v1/transactions/:transaction_id

Parâmetros de URL

Parâmetro Tipo Descrição
transaction_id string ID único da transação que deseja consultar

Resposta

JSON Response 
{
"id": "c22dc7e1-8b10-4580-9dc4-ebf78ceca475",
"external_id": null,
"status": "PENDING",
"amount": 10,
"payment_method": "PIX",
"customer": {
  "name": "Jon doe sudo",
  "email": "niriv77914@dwriters.com",
  "phone": "00000000000",
  "document": "24125439095",
  "address": {
    "cep": "32323232",
    "city": "Florianopolis",
    "state": "SC",
    "number": "82",
    "street": "Florianopolis Centro",
    "complement": "ALTOS",
    "neighborhood": "Centro"
  }
},
"created_at": "2025-04-03T20:45:33.855Z"
}

Criar Transação

Este endpoint permite criar uma nova transação em nosso sistema.

POST https://api.spedpay.com.br/v1/transactions

Corpo da Requisição

JSON Request 
{
"external_id": "string",
"total_amount": number,
"payment_method": "PIX",
"webhook_url": "string",
"items": [
  {
    "id": "string",
    "title": "string",
    "description": "string",
    "price": number,
    "quantity": number,
    "is_physical": boolean
  }
],
"ip": "string",
"customer": {
  "name": "string",
  "email": "string",
  "phone": "string",
  "document_type": "CPF" | "CNPJ",
  "document": "string"
}
}

Consultar Transação

Este endpoint permite consultar os detalhes de uma transação previamente criada.

GET https://api.spedpay.com.br/v1/transactions/:transaction_id

Parâmetros de URL

Parâmetro Tipo Descrição
transaction_id string ID único da transação que deseja consultar

Resposta

JSON Response 
{
"id": "c22dc7e1-8b10-4580-9dc4-ebf78ceca475",
"external_id": null,
"status": "PENDING",
"amount": 10,
"payment_method": "PIX",
"customer": {
  "name": "Jon doe sudo",
  "email": "niriv77914@dwriters.com",
  "phone": "00000000000",
  "document": "24125439095",
  "address": {
    "cep": "32323232",
    "city": "Florianopolis",
    "state": "SC",
    "number": "82",
    "street": "Florianopolis Centro",
    "complement": "ALTOS",
    "neighborhood": "Centro"
  }
},
"created_at": "2025-04-03T20:45:33.855Z"
}

Parâmetros

Abaixo estão os parâmetros necessários para criar uma transação:

Parâmetro Tipo Descrição
external_id string Identificador único externo da transação
total_amount number Valor total da transação em reais
payment_method string Método de pagamento (atualmente apenas "PIX")
webhook_url string URL para receber notificações de mudança de status
items array Lista de itens incluídos na transação
ip string Endereço IP do cliente
customer object Informações do cliente

Resposta

A API retorna um objeto JSON com os detalhes da transação criada:

JSON Response 
{
"id": "string",
"external_id": "string",
"status": "AUTHORIZED" | "PENDING" | "CHARGEBACK" | "FAILED" | "IN_DISPUTE",
"total_value": number,
"customer": {
  "email": "string",
  "name": "string"
},
"payment_method": "string",
"pix": {
  "payload": "string"
},
"hasError": boolean
}

Status da Transação

Os possíveis valores para o campo status são:

  • PENDING - Aguardando pagamento
  • AUTHORIZED - Pagamento aprovado
  • FAILED - Pagamento falhou
  • CHARGEBACK - Estorno solicitado
  • IN_DISPUTE - Em disputa

Erros

A API pode retornar os seguintes códigos de erro:

Código Descrição
401 API Secret não fornecida ou inválida
400 Dados inválidos na requisição
500 Erro interno do servidor

Webhook

Notificações de mudança de status são enviadas para a URL configurada:

Payload do Webhook 
{
"id": "string",
"external_id": "string",
"total_amount": number,
"status": "AUTHORIZED" | "PENDING" | "CHARGEBACK" | "FAILED" | "IN_DISPUTE",
"payment_method": "string"
}
Nota Recomendamos implementar retry e validação de assinatura nos webhooks para garantir a segurança e confiabilidade das notificações.

Boas Práticas

Para garantir a segurança e confiabilidade do seu sistema de webhooks:

  • Implemente um mecanismo de retry para lidar com falhas temporárias
  • Verifique a assinatura do webhook para garantir a autenticidade
  • Responda rapidamente com código 200 para confirmar o recebimento
  • Processe o webhook de forma assíncrona para evitar timeouts

Cashout

Este endpoint permite criar uma transação de cashout (saque) usando PIX.

POST https://api.spedpay.com.br/v1/cashout

Corpo da Requisição

JSON Request 
{
"external_id": "string"
"pix_key": "string",
"pix_type": "CPF" | "CNPJ" | "EMAIL" | "PHONE" | "RANDOM",
"amount": number
"webhook_url": "https://suapipostback.com"
}

Parâmetros

Parâmetro Tipo Descrição
pix_key string Chave PIX para o cashout. Deve ser um CPF, CNPJ, e-mail, telefone ou chave aleatória válida.
pix_type enum Tipo da chave PIX. Valores possíveis: CPF, CNPJ, EMAIL, PHONE, RANDOM
amount number Valor do cashout em reais. Deve ser maior que 0.01
webhook_url string Sua url de api para receber os eventos do Cashout

Formatos de Chave PIX

Formatos Aceitos

  • CPF: 11 dígitos numéricos
  • CNPJ: 14 dígitos numéricos
  • E-mail: Endereço de e-mail válido
  • Telefone: +55 seguido de 10 ou 11 dígitos
  • Chave aleatória: 32 a 36 caracteres alfanuméricos e hífens
Nota A chave PIX deve corresponder ao tipo especificado no campo pix_type.

Exemplo de Requisição

Exemplo 
{
"pix_key": "12345678900",
"pix_type": "CPF",
"amount": 100.50
}

Resposta

A API retorna um objeto JSON com os detalhes da transação de cashout criada:

JSON Response 
{
"id": "string",
"status": "PENDING" | "COMPLETED" | "FAILED",
"amount": number,
"pix_key": "string",
"pix_type": "CPF" | "CNPJ" | "EMAIL" | "PHONE" | "RANDOM",
"created_at": "string (ISO 8601 date)"
}

Erros Específicos

Código Descrição
400 Formato de chave PIX inválido ou não correspondente ao tipo especificado
400 Valor de cashout abaixo do mínimo permitido

Webhook de Cashout

Este webhook é disparado sempre que um cashout muda de status. Use-o para acompanhar em tempo real a aprovação ou falha de um saque solicitado.

Possíveis Status

  • approved – Cashout aprovado
  • pending – Cashout pendente
  • processing – Cashout em processamento
  • failed – Falha no processamento
  • rejected – Cashout rejeitado

Exemplo de Payload

JSON Payload 
{
"id": "f2c5f6e7-f710-437f-ad8c-44022316123ed",
"external_id": "sua_referencia_123456789",
"status": "approved",
"total_amount": 1.2,
"pix_key": "000000000000"
}