Primeiros Passos

Endpoints da API

Webhooks

Referência

Documentação Oficial

API docs

Documentação completa para integrar soluções de pagamento com transações PIX e gerenciamento de cashouts. Construída para desenvolvedores que buscam simplicidade e robustez.

Início Rápido

Configure sua integração em minutos com nossos exemplos práticos e guias detalhados.

API RESTful

Métodos HTTP padrão com corpos de requisição e resposta em JSON limpo e consistente.

Webhooks

Notificações em tempo real para atualizações de status de transações e cashouts.

Guia de Integração

Para começar a usar nossa API de Pagamentos, siga estes passos:

Obtenha suas credenciais de API no painel administrativo
Configure os cabeçalhos de autenticação em suas requisições
Implemente endpoints de webhook para receber atualizações de status

Ambiente de Produção

Nossa API está disponível em ambiente de produção para processar pagamentos reais.

https://api.simplifypayments.com.br

URL Base da API

Todas as requisições da API devem ser feitas para o seguinte endpoint base:

BASE URL

https://api.simplifypayments.com.br

HTTPS

Importante

Todos os endpoints documentados abaixo devem ser anexados a esta URL base. Por exemplo, para criar uma transação, faça uma requisição para https://api.simplifypayments.com.br/v1/transactions.

Autenticação

A API utiliza autenticação por chave de API através de cabeçalhos de requisição.

Cabeçalho de Autenticação

Inclua seu API secret no cabeçalho da requisição para autenticação.

Cabeçalho de Autenticação

http

api-secret: SEU_API_SECRET_AQUI

Nota de Segurança

Você pode obter seu API Secret na seção integrações → API de pagamentos no painel da sua conta. Mantenha seu API secret seguro e nunca o exponha em código do lado do cliente.

Exemplo de Requisição

cURL

bash

curl -X GET "https://api.simplifypayments.com.br/v1/account-info" \
  -H "api-secret: seu_api_secret_aqui" \
  -H "Content-Type: application/json"

Exemplo JavaScript

JavaScript

javascript

const response = await fetch('https://api.simplifypayments.com.br/v1/account-info', {
  headers: {
    'api-secret': 'seu_api_secret_aqui',
    'Content-Type': 'application/json'
  }
});

Informações da Conta

Recupera informações sobre a conta associada à chave de API.

GET

https://api.simplifypayments.com.br/v1/account-info

v1.0

Informação

Este endpoint não requer parâmetros adicionais. As informações retornadas são baseadas na chave de API fornecida no cabeçalho de autenticação.

Resposta

Resposta de Informações da Conta

json

{
  "email": "joao.silva@exemplo.com",
  "name": "João Silva",
  "document": "12345678901"
}

Campos da Resposta

Parâmetro	Tipo	Descrição
`email`	string	Endereço de email da conta
`name`	string	Nome do titular da conta
`document`	string	Número do documento da conta (CPF/CNPJ)

Consultar Transação

Recupera detalhes de uma transação previamente criada usando seu ID único.

GET

https://api.simplifypayments.com.br/v1/transactions/{transaction_id}

v1.0

Parâmetros da URL

Parâmetro	Tipo	Descrição
`transaction_id` obrigatório	string	Identificador único da transação que deseja consultar

Exemplo de Requisição

cURL

bash

curl -X GET "https://api.simplifypayments.com.br/v1/transactions/c22dc7e1-8b10-4580-9dc4-ebf78ceca475" \
  -H "api-secret: seu_api_secret_aqui" \
  -H "Content-Type: application/json"

Resposta

Resposta da Transação

json

{
  "id": "c22dc7e1-8b10-4580-9dc4-ebf78ceca475",
  "external_id": "pedido_12345",
  "status": "PENDING",
  "amount": 100.50,
  "payment_method": "PIX",
  "customer": {
    "name": "João Silva",
    "email": "joao.silva@exemplo.com",
    "phone": "11999999999",
    "document": "12345678901",
    "address": {
      "cep": "01234567",
      "city": "São Paulo",
      "state": "SP",
      "number": "123",
      "street": "Rua das Flores",
      "complement": "Apt 45",
      "neighborhood": "Centro"
    }
  },
  "created_at": "2024-01-15T10:30:00.000Z"
}

Campos da Resposta

Parâmetro	Tipo	Descrição
`id`	string	Identificador único da transação
`external_id`	string	Seu ID de referência externa
`status`	TransactionStatus	Status atual da transação
`amount`	number	Valor da transação em BRL
`payment_method`	string	Método de pagamento utilizado
`customer`	Customer	Objeto com informações do cliente
`created_at`	string	Timestamp de criação da transação (ISO 8601)

Criar Transação

Cria uma nova transação de pagamento no sistema com todos os detalhes necessários.

POST

https://api.simplifypayments.com.br/v1/transactions

v1.0

Interface TypeScript

Definições de Tipo

typescript

interface CreateTransactionRequest {
  external_id?: string;
  total_amount: number;
  payment_method: "PIX";
  webhook_url?: string;
  items: TransactionItem[];
  ip?: string;
  customer: Customer;
}

interface TransactionItem {
  id: string;
  title: string;
  description?: string;
  price: number;
  quantity: number;
  is_physical: boolean;
}

interface Customer {
  name: string;
  email: string;
  phone: string;
  document_type: "CPF" | "CNPJ";
  document: string;
}

Exemplo de Requisição

Criar Transação - Requisição

json

{
  "external_id": "pedido_12345",
  "total_amount": 100.50,
  "payment_method": "PIX",
  "webhook_url": "https://sua-api.com/webhooks/transactions",
  "items": [
    {
      "id": "item_001",
      "title": "Assinatura Premium",
      "description": "Assinatura mensal premium",
      "price": 100.50,
      "quantity": 1,
      "is_physical": false
    }
  ],
  "ip": "192.168.1.1",
  "customer": {
    "name": "João Silva",
    "email": "joao.silva@exemplo.com",
    "phone": "11999999999",
    "document_type": "CPF",
    "document": "12345678901"
  }
}

Parâmetros da Requisição

Parâmetro	Tipo	Descrição
`external_id`	string	Sua referência única para esta transação
`total_amount` obrigatório	number	Valor total da transação em BRL
`payment_method` obrigatório	string	Método de pagamento (atualmente apenas 'PIX')
`webhook_url`	string	URL para receber notificações de mudança de status
`items` obrigatório	TransactionItem[]	Array de itens na transação
`ip`	string	Endereço IP do cliente
`customer` obrigatório	Customer	Informações do cliente

Resposta

Criar Transação - Resposta

json

{
  "id": "c22dc7e1-8b10-4580-9dc4-ebf78ceca475",
  "external_id": "pedido_12345",
  "status": "PENDING",
  "total_value": 100.50,
  "customer": {
    "email": "joao.silva@exemplo.com",
    "name": "João Silva"
  },
  "payment_method": "PIX",
  "pix": {
    "payload": "00020126580014br.gov.bcb.pix..."
  },
  "hasError": false
}

Dica de Implementação

O campo pix.payload contém o código PIX que deve ser apresentado ao cliente para pagamento. Este código pode ser usado para gerar um QR Code ou ser copiado diretamente.

Cashout (Saque)

Cria uma nova transação de cashout (saque) utilizando PIX para transferir fundos.

POST

https://api.simplifypayments.com.br/v1/cashout

v1.0

Interface TypeScript

Definição de Tipo

typescript

interface CreateCashoutRequest {
  external_id?: string;
  pix_key: string;
  pix_type: "CPF" | "CNPJ" | "EMAIL" | "PHONE" | "RANDOM";
  amount: number;
  webhook_url?: string;
}

Exemplo de Requisição

Criar Cashout - Requisição

json

{
  "external_id": "saque_12345",
  "pix_key": "joao.silva@exemplo.com",
  "pix_type": "EMAIL",
  "amount": 250.00,
  "webhook_url": "https://sua-api.com/webhooks/cashouts"
}

Parâmetros da Requisição

Parâmetro	Tipo	Descrição
`external_id`	string	Sua referência única para este cashout
`pix_key` obrigatório	string	Chave PIX para o destino do cashout
`pix_type` obrigatório	PixKeyType	Tipo da chave PIX sendo utilizada
`amount` obrigatório	number	Valor do cashout em BRL (mínimo 0.01)
`webhook_url`	string	URL para receber notificações de status do cashout

Formatos de Chave PIX

CPF

11 dígitos numéricos

12345678901

CNPJ

14 dígitos numéricos

12345678000195

Endereço de email válido

usuario@exemplo.com

PHONE

+55 seguido de 10-11 dígitos

+5511999999999

RANDOM

32-36 caracteres alfanuméricos

123e4567-e12b-12d3-a456-426614174000

Validação Importante

A chave PIX deve corresponder exatamente ao tipo especificado no campo pix_type. Chaves inválidas resultarão em erro 400.

Resposta

Criar Cashout - Resposta

json

{
  "success": true,
  "message": "Cashout criado com sucesso",
  "data": {
    "withdraw_id": "bb0fb3cb-015f-4604-8532-133a78c0c3e1",
    "cashout_id": "bb0fb3cb-015f-4604-8532-133a78c0c3e1",
    "is_pending": true
  }
}

Webhooks de Transação

Receba notificações em tempo real quando o status das transações mudar.

Payload do Webhook

Este payload é enviado para sua URL de webhook sempre que o status de uma transação muda.

Interface do Payload

typescript

interface TransactionWebhook {
  id: string;
  external_id: string | null;
  total_amount: number;
  status: "AUTHORIZED" | "PENDING" | "CHARGEBACK" | "FAILED" | "IN_DISPUTE";
  payment_method: string;
}

Exemplo de Payload

Atualização de Status da Transação

json

{
  "id": "c22dc7e1-8b10-4580-9dc4-ebf78ceca475",
  "external_id": "pedido_12345",
  "total_amount": 100.50,
  "status": "AUTHORIZED",
  "payment_method": "PIX"
}

Melhores Práticas para Webhooks

Responda com código HTTP 200 para confirmar recebimento
Implemente lógica de retry para falhas temporárias
Verifique assinaturas de webhook para segurança

Processe webhooks de forma assíncrona
Use chaves de idempotência para duplicatas
Mantenha logs detalhados para debugging

Exemplo de Implementação

Node.js + Express

javascript

app.post('/webhooks/transactions', (req, res) => {
  const { id, external_id, total_amount, status, payment_method } = req.body;
  
  // Processar o webhook de forma assíncrona
  processTransactionWebhook({
    id,
    external_id,
    total_amount,
    status,
    payment_method
  });
  
  // Responder imediatamente com 200
  res.status(200).json({ received: true });
});

Webhooks de Cashout

Seja notificado quando ocorrerem mudanças de status nos cashouts.

Status Possíveis do Cashout

approved

Cashout aprovado e processado

pending

Cashout aguardando processamento

processing

Cashout sendo processado

failed

Falha no processamento

rejected

Cashout rejeitado

Exemplo de Payload

Atualização de Status do Cashout

json

{
  "id": "f2c5f6e7-f710-437f-ad8c-44022316123e",
  "external_id": "saque_12345",
  "status": "approved",
  "total_amount": 250.00,
  "pix_key": "joao.silva@exemplo.com"
}

Formato de Resposta

Formatos de resposta padrão e códigos de status utilizados pela API.

Resposta de Sucesso

Formato de Sucesso

json

{
  "data": {
    // Dados da resposta aqui
  },
  "success": true
}

Resposta de Erro

Formato de Erro

json

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Dados de requisição inválidos",
    "details": []
  },
  "success": false
}

Status das Transações

Valores possíveis para o campo status nas transações

PENDING

Transação aguardando pagamento

AUTHORIZED

Pagamento aprovado e processado

FAILED

Falha no processamento do pagamento

CHARGEBACK

Chargeback foi iniciado

IN_DISPUTE

Transação está em disputa

Códigos de Erro

Códigos de status HTTP e respostas de erro retornadas pela API.

400

Bad Request

A requisição era inválida ou não pode ser atendida. Causas comuns:

Parâmetros obrigatórios ausentes
Valores ou formatos de parâmetros inválidos
JSON malformado no corpo da requisição

401

Unauthorized

Falha na autenticação. Causas comuns:

Cabeçalho API secret ausente
API secret inválido ou expirado
API secret para ambiente incorreto

404

Not Found

O recurso solicitado não foi encontrado. Causas comuns:

URL do endpoint inválida
ID da transação não existe
Recurso foi deletado

500

Internal Server Error

Ocorreu um erro inesperado em nossos servidores. Tente novamente mais tarde ou entre em contato com o suporte se o problema persistir.

Dica de Debugging

Todos os erros incluem um campo message com detalhes específicos sobre o problema. Use essas mensagens para diagnosticar e corrigir problemas de integração rapidamente.