Documentação da API

Introdução

Bem-vindo à documentação completa da nossa Interface de Programação de Aplicações. Esta Interface foi desenvolvida para facilitar a integração com nosso sistema de pagamentos e saques, incluindo pagamentos via PIX, emissão de boletos e vendas no cartão de crédito, com suporte a notificações por retorno de chamada quando configurado.

Endereço base: https://api.ejspay.com

Recursos Disponíveis

  • Autenticação: Geração de token JSON Web Token para acesso seguro aos endpoints
  • Depósito: Criação de depósitos com geração de código para pagamento por PIX
  • Saque: Solicitação de saques utilizando chaves PIX e cálculo de taxas
  • Boletos: Criação de cobranças por boleto, consulta de linha digitável e obtenção de documentos em formato Portable Document Format
  • Cartão de Crédito: Criação de vendas (à vista, parcelado ou pré-autorizado), consulta, captura e estorno
  • Webhooks: Notificações para informar o status das transações quando um endereço de retorno de chamada é informado

Autenticação

O endpoint de autenticação permite que os usuários façam login utilizando suas credenciais, recebendo um token JSON Web Token que deverá ser enviado no cabeçalho das requisições protegidas.

POST /api/auth/login

Parâmetros

Atributo Tipo Descrição
client_id string Identificador do cliente fornecido no cadastro
client_secret string Chave secreta do cliente para autenticação

Exemplo de Requisição

{
  "client_id": "seu_cliente_id",
  "client_secret": "seu_cliente_secreto"
}

Resposta de Sucesso

{
  "message": "Authentication successful.",
  "token": "seu_token_json_web_token",
  "user": {
    "id": 1,
    "name": "Nome do Usuário",
    "email": "email@exemplo.com",
    "client_id": "seu_cliente_id"
  }
}

Depósito

Este endpoint permite criar um depósito e gerar um código PIX para efetuar o pagamento.

POST /api/payments/deposit
Requer autenticação: Authorization: Bearer {token}

Parâmetros

Atributo Tipo Descrição
amount number Valor do depósito
external_id string Identificador único da transação externa (para controle idempotente)
clientCallbackUrl string Endereço para notificações de status do depósito
payer object Dados do pagador

Objeto payer

Atributo Tipo Descrição
name string Nome completo do pagador
email string Endereço de correio eletrônico do pagador
document string Documento do pagador (Cadastro de Pessoas Físicas ou Cadastro Nacional da Pessoa Jurídica)

Exemplo de Requisição

{
  "amount": 100.00,
  "external_id": "id_unico_12345",
  "clientCallbackUrl": "https://seuservidor.com/retorno-de-chamada",
  "payer": {
    "name": "João da Silva",
    "email": "joao@example.com",
    "document": "12345678901"
  }
}

Resposta de Sucesso

{
  "message": "Deposit created successfully.",
  "qrCodeResponse": {
    "transactionId": "id_da_transacao",
    "status": "PENDING",
    "qrcode": "00020101021226930014br.gov.bcb.pix2571qrcode-h.pix...",
    "amount": 100.00
  }
}

Saque

Este endpoint permite solicitar saque utilizando uma chave PIX, com verificação de saldo, cálculo de taxas e atualização do status da transação.

POST /api/withdrawals/withdraw
Requer autenticação: Authorization: Bearer {token}

Parâmetros

Atributo Tipo Descrição
amount number Valor do saque
external_id string Identificador único da transação externa
pix_key string Chave PIX do destinatário
key_type string Tipo da chave (EMAIL, CPF, CNPJ ou PHONE)
description string Descrição opcional do saque
clientCallbackUrl string Endereço para notificações de status do saque

Exemplo de Requisição

{
  "amount": 50.00,
  "external_id": "external-12345",
  "pix_key": "exemplo@pix.com",
  "key_type": "EMAIL",
  "description": "Saque referente ao pedido 123",
  "clientCallbackUrl": "https://seuservidor.com/retorno-de-chamada"
}

Resposta de Sucesso

{
  "transaction_id": "transaction-67890",
  "status": "PENDING",
  "amount": 50.00,
  "fee": 2.50
}

Boletos

Os endpoints de boletos permitem criar cobranças avulsas ou parceladas, obter a linha digitável, e realizar a visualização ou download do documento em formato Portable Document Format por meio de um proxy seguro.

POST /api/v1/boletos
Requer autenticação: Authorization: Bearer {token}

Parâmetros

Atributo Tipo Descrição
amount number Valor da cobrança
dueDate string Data de vencimento no formato AAAA-MM-DD
description string Descrição opcional da cobrança
clientCallbackUrl string Endereço de retorno de chamada para atualizações do boleto
installmentCount integer Quantidade de parcelas (para parcelamento deve ser maior ou igual a 2)
installmentValue number Valor de cada parcela (quando parcelado)
discount object Desconto (opcional)
interest object Juros (opcional)
fine object Multa (opcional)
payer object Dados do pagador

Objeto payer

Atributo Tipo Descrição
name string Nome do pagador
email string Endereço de correio eletrônico do pagador (opcional)
document string Documento do pagador (Cadastro de Pessoas Físicas ou Cadastro Nacional da Pessoa Jurídica)
phone string Telefone do pagador (opcional)

Exemplo de Requisição

{
  "amount": 200.50,
  "dueDate": "2025-10-05",
  "description": "Cobrança referente ao pedido 123",
  "clientCallbackUrl": "https://seuservidor.com/retorno-de-chamada/boletos",
  "installmentCount": 10,
  "installmentValue": 200.00,
  "discount": {
    "value": 10,
    "dueDateLimitDays": 5,
    "type": "PERCENTAGE"
  },
  "interest": { "value": 1 },
  "fine": { "value": 2 },
  "payer": {
    "name": "Fulano de Tal",
    "email": "fulano@email.com",
    "document": "12345678909",
    "phone": "11999999999"
  }
}

Resposta de Sucesso

{
  "message": "Boleto criado com sucesso.",
  "data": {
    "id": 1,
    "status": "PENDING",
    "amount": 200.5,
    "dueDate": "2025-10-05",
    "pdfUrl": "https://sua-api.com/api/v1/boletos/1/pdf",
    "installment": {
      "paymentBookUrl": "https://sua-api.com/api/v1/boletos/installments/INSTALLMENT_ID/payment-book"
    },
    "bankSlip": {
      "identificationField": "linha_digitavel",
      "nossoNumero": "nosso_numero",
      "barCode": "codigo_de_barras",
      "daysAfterDueDateToRegistrationCancellation": 30,
      "bankSlipUrl": "endereco_do_boleto_no_provedor"
    },
    "pix": null,
    "creditCard": null,
    "payer": {
      "name": "Fulano de Tal",
      "document": "12345678909",
      "email": "fulano@email.com",
      "phone": "11999999999"
    },
    "providerReferences": {
      "asaasPaymentId": "PROVIDER_PAYMENT_ID",
      "asaasInstallmentId": "PROVIDER_INSTALLMENT_ID"
    }
  }
}
GET /api/v1/boletos/{id}/identification-field
Requer autenticação: Authorization: Bearer {token}

Parâmetros de caminho

Atributo Tipo Descrição
id integer Identificador interno do boleto

Resposta de Sucesso

{
  "identificationField": "linha_digitavel",
  "nossoNumero": "nosso_numero",
  "barCode": "codigo_de_barras"
}
GET /api/v1/boletos/{id}/pdf

Este endpoint retorna o documento do boleto em formato Portable Document Format por meio de proxy. Ele é público e não exige autenticação.

Parâmetros de caminho

Atributo Tipo Descrição
id integer Identificador interno do boleto

Resposta

Conteúdo binário: application/pdf
GET /api/v1/boletos/installments/{installmentId}/payment-book
Requer autenticação: Authorization: Bearer {token}

Parâmetros de caminho

Atributo Tipo Descrição
installmentId string Identificador do parcelamento no provedor

Resposta

Conteúdo binário: application/pdf

Cartão de Crédito

Os endpoints de cartão de crédito permitem criar uma venda (à vista, parcelado ou pré-autorizado), consultar uma venda pelo identificador interno, capturar uma pré-autorização e estornar uma venda. Para criação, é obrigatório informar a data de vencimento e um meio de pagamento: dados do cartão (creditCard) ou token do cartão (creditCardToken).

POST /api/v1/card/payments
Requer autenticação: Authorization: Bearer {token}

Regras importantes:
• Para cartão é obrigatório informar dueDate.
• O titular deve possuir phone (com DDD, 10 a 11 dígitos) e postalCode (Código de Endereçamento Postal com 8 dígitos, sem hífen).
• Para parcelamento (installmentCount maior ou igual a 2), informe installmentValue ou totalValue.
• Envie creditCard ou creditCardToken.

Parâmetros principais

Atributo Tipo Descrição
amount number Valor da venda
description string Descrição opcional
externalReference string Referência externa para conciliação
authorizeOnly boolean Se verdadeiro, cria pré-autorização (captura deve ser feita em endpoint específico)
installmentCount integer Número de parcelas
installmentValue number Valor de cada parcela
totalValue number Valor total (alternativa ao installmentValue em alguns cenários)
dueDate string Data de vencimento no formato AAAA-MM-DD
remoteIp string Endereço de IP do comprador (opcional)
payer object Dados do titular
creditCard object Dados do cartão (opcional se creditCardToken for enviado)
creditCardToken string Token do cartão (opcional se creditCard for enviado)

Objeto payer

Atributo Tipo Descrição
name string Nome do titular
email string Endereço de correio eletrônico do titular
document string Documento do titular (somente dígitos)
phone string Telefone do titular com DDD (10 a 11 dígitos)
postalCode string Código de Endereçamento Postal (8 dígitos, sem hífen)
addressNumber string Número do endereço (opcional)
addressComplement string Complemento do endereço (opcional)

Objeto creditCard (quando usado)

Atributo Tipo Descrição
holderName string Nome impresso no cartão
number string Número do cartão
expiryMonth string Mês de validade (dois dígitos)
expiryYear string Ano de validade (quatro dígitos)
ccv string Código de verificação

Exemplo de Requisição (enviando dados do cartão)

{
  "amount": 129.90,
  "description": "Pedido 056984",
  "externalReference": "056984",
  "authorizeOnly": false,
  "installmentCount": 3,
  "installmentValue": 43.30,
  "totalValue": 129.90,
  "dueDate": "2025-10-21",
  "remoteIp": "203.0.113.10",
  "payer": {
    "name": "John Doe",
    "email": "john@example.com",
    "document": "12345678909",
    "phone": "11987654321",
    "postalCode": "01001000",
    "addressNumber": "123",
    "addressComplement": "Sala 12"
  },
  "creditCard": {
    "holderName": "JOHN DOE",
    "number": "4111111111111111",
    "expiryMonth": "03",
    "expiryYear": "2026",
    "ccv": "123"
  }
}

Exemplo de Requisição (enviando token do cartão)

{
  "amount": 129.90,
  "description": "Pedido 056984",
  "externalReference": "056984",
  "authorizeOnly": false,
  "dueDate": "2025-10-21",
  "payer": {
    "name": "John Doe",
    "email": "john@example.com",
    "document": "12345678909",
    "phone": "11987654321",
    "postalCode": "01001000"
  },
  "creditCardToken": "68b259fb-f506-468e-bc5b-ce65dd478464"
}

Resposta de Sucesso

{
  "message": "Pagamento criado com sucesso.",
  "data": {
    "id": 10,
    "status": "PENDING",
    "amount": 129.9,
    "netValue": 120.12,
    "brand": "VISA",
    "last4": "1111",
    "invoiceUrl": "endereco_da_fatura",
    "receiptUrl": "endereco_do_comprovante",
    "providerReferences": {
      "asaasPaymentId": "PROVIDER_PAYMENT_ID",
      "asaasInstallmentId": "PROVIDER_INSTALLMENT_ID"
    }
  }
}
GET /api/v1/card/payments/{id}
Requer autenticação: Authorization: Bearer {token}

Parâmetros de caminho

Atributo Tipo Descrição
id integer Identificador interno da venda no cartão

Resposta de Sucesso

{
  "id": 10,
  "userId": 1,
  "amount": 129.9,
  "netValue": 120.12,
  "status": "CONFIRMED",
  "brand": "VISA",
  "last4": "1111",
  "authorizeOnly": false,
  "installmentCount": 3,
  "installmentNumber": 1,
  "invoiceUrl": "endereco_da_fatura",
  "receiptUrl": "endereco_do_comprovante",
  "providerReferences": {
    "asaasPaymentId": "PROVIDER_PAYMENT_ID",
    "asaasInstallmentId": "PROVIDER_INSTALLMENT_ID"
  },
  "dates": {
    "dueDate": "2025-10-21",
    "confirmedDate": "2025-10-21",
    "clientPaymentDate": "2025-10-21",
    "creditDate": "2025-10-22",
    "estimatedCreditDate": "2025-10-22"
  }
}
POST /api/v1/card/payments/{id}/capture
Requer autenticação: Authorization: Bearer {token}

Parâmetros de caminho

Atributo Tipo Descrição
id integer Identificador interno da venda pré-autorizada

Corpo da Requisição

{}

Resposta de Sucesso

{
  "message": "Pagamento capturado com sucesso.",
  "data": {
    "id": 10,
    "status": "CONFIRMED",
    "netValue": 120.12
  }
}
POST /api/v1/card/payments/{id}/refund
Requer autenticação: Authorization: Bearer {token}

Parâmetros de caminho

Atributo Tipo Descrição
id integer Identificador interno da venda a ser estornada

Corpo da Requisição

{}

Resposta de Sucesso

{
  "message": "Pagamento estornado com sucesso.",
  "data": {
    "id": 10,
    "status": "REFUNDED"
  }
}

Webhooks

Os webhooks permitem que seu sistema receba notificações em tempo real sobre atualizações no status das transações. Para depósitos, saques e boletos, utilize o campo clientCallbackUrl ao criar a solicitação.

Webhook de Depósito

Exemplo de payload

{
  "transaction_id": "id_da_transacao",
  "status": "PENDING",
  "amount": 100.00,
  "type": "Deposit"
}
{
  "transaction_id": "id_da_transacao",
  "status": "COMPLETED",
  "amount": 100.00,
  "type": "Deposit"
}
Webhook de Saque

Exemplo de payload

{
  "transaction_id": "transaction-67890",
  "status": "PENDING",
  "amount": 50.00,
  "type": "Withdraw"
}
{
  "transaction_id": "transaction-67890",
  "status": "COMPLETED",
  "amount": 50.00,
  "type": "Withdraw"
}
Webhook de Boleto

Exemplo de payload

{
  "id": 1,
  "type": "Boleto",
  "status": "PENDING",
  "amount": 200.5,
  "dueDate": "2025-10-05",
  "createdAt": "2025-10-01T12:00:00.000Z"
}
{
  "id": 1,
  "type": "Boleto",
  "status": "COMPLETED",
  "amount": 200.5,
  "dueDate": "2025-10-05",
  "createdAt": "2025-10-01T12:00:00.000Z"
}
Webhook de CARD

Exemplo de payload

{
  "id": 1,
  "type": "CARD",
  "status": "PENDING",
  "amount": 200.5,
  "dueDate": "2025-10-05",
  "createdAt": "2025-10-01T12:00:00.000Z"
}
{
  "id": 1,
  "type": "CARD",
  "status": "COMPLETED",
  "amount": 200.5,
  "dueDate": "2025-10-05",
  "createdAt": "2025-10-01T12:00:00.000Z"
}

Códigos de Erro

A Interface utiliza códigos HyperText Transfer Protocol padrão para indicar o resultado das operações. A seguir, os principais códigos e suas descrições.

200
OK
Requisição processada com sucesso
400
Bad Request
Dados inválidos ou campos obrigatórios ausentes
401
Unauthorized
Credenciais inválidas ou token não enviado
403
Forbidden
Acesso negado ao recurso
404
Not Found
Recurso não encontrado ou rota incorreta
500
Internal Server Error
Erro no servidor durante o processamento
502
Bad Gateway
Falha ao comunicar com o provedor de pagamento
Exemplo de Resposta de Erro 
{
  "message": "Requisição inválida.",
  "errors": [
    "Campo amount é obrigatório.",
    "Campo dueDate é obrigatório (AAAA-MM-DD)."
  ]
}