Referência da API

Bem-vindo à Referência da API PaysGator. Esta documentação fornece informações detalhadas sobre nossos endpoints de API, estruturas de solicitação e formatos de resposta.

URL Base

Todas as solicitações de API devem ser feitas para a seguinte URL base:

https://paysgator.com/api/v1

Autenticação

A API usa autenticação por Chave de API (API Key). Inclua sua chave no cabeçalho X-Api-Key de cada solicitação. Você pode usar chaves LIVE ou TEST para controlar o modo de transação.

X-Api-Key: SUA_CHAVE_API

Endpoints

Pagamentos (Payments)

Criar Pagamento (Create Payment)

Cria uma transação de pagamento com um link de pagamento associado.

• URL: /payment/create
• Método: POST
• Corpo da Solicitação:

Campo	Tipo	Obrigatório	Descrição
amount	number	Sim	Valor do pagamento (ex: 100.00).
currency	string	Sim	Código de moeda ISO 4217 (ex: USD, MZN).
payment_methods	array	Não	Lista de métodos de pagamento permitidos (ex: ["MPESA", "CARD"]).
returnUrl	string	Não	URL para redirecionar após o pagamento.
fields	array	Não	Campos a coletar do cliente (name, email, phone, address).
externalTransactionId	string	Não	Seu ID de referência externa.
metadata	object	Não	Metadados adicionais.

• Resposta (200 OK):
  • success: true
  • data:
    • paymentlinkId: UUID
    • checkoutUrl: URL da página de pagamento
    • transactionId: UUID

Confirmar Pagamento (Confirm Payment)

Confirma um pagamento diretamente de um link de pagamento (para métodos do tipo "Confirm").

• URL: /payment/confirm
• Método: POST
• Corpo da Solicitação:

Campo	Tipo	Obrigatório	Descrição
paymentLinkId	string	Sim	O ID do link de pagamento.
paymentMethod	string	Sim	O método a ser usado (ex: MPESA).
payment_fields	object	Não	Campos específicos do método (ex: { "phoneNumber": "..." }).
customer	object	Não	Informações do cliente (name, email, phone, address, country).

• Resposta (200 OK):
  • success: true
  • data:
    • transactionId: UUID
    • fee: Taxa da transação
    • netAmount: Valor líquido

Carteira (Wallet)

Obter Saldo da Carteira (Get Wallet Balance)

Recupera o saldo da carteira associada à chave da API.

• URL: /wallet/balance
• Método: GET
• Resposta (200 OK):
  • walletId: UUID
  • currency: Código da moeda
  • balance: Saldo como string
  • mode: LIVE ou TEST

Transações (Transactions)

Obter Transação (Get Transaction)

Recupera detalhes de uma transação específica.

• URL: /transactions/{id}
• Método: GET
• Parâmetros:
  • id (caminho): UUID da transação
• Resposta (200 OK):
  • id: UUID
  • amount: número
  • currency: string
  • status: PENDING, SUCCESS, FAILED, REFUNDED
  • method: método de pagamento usado
  • createdAt: data ISO
  • mode: LIVE ou TEST

Assinaturas (Subscriptions)

Criar Assinatura (Create Subscription)

Inicia uma nova assinatura no estado PAUSED e retorna uma URL de checkout.

• URL: /subscription/create
• Método: POST
• Corpo da Solicitação:

Campo	Tipo	Obrigatório	Descrição
planId	string	Sim	ID do plano de assinatura.
customerEmail	string	Sim	Endereço de e-mail do cliente.
customerName	string	Não	Nome do cliente.
metadata	object	Não	Metadados adicionais.

• Resposta (200 OK):
  • success: true
  • data:
    • subscriptionId: UUID
    • checkoutUrl: URL da página de pagamento
    • status: PAUSED

Obter Assinatura (Get Subscription)

Recupera detalhes de uma assinatura específica.

• URL: /subscription/{id}
• Método: GET
• Parâmetros:
  • id (caminho): UUID da assinatura
• Resposta (200 OK):
  • success: true
  • data:
    • id: UUID
    • planId: UUID
    • customerEmail: string
    • status: ACTIVE, CANCELED, PAST_DUE, PAUSED
    • currentPeriodStart: data ISO
    • currentPeriodEnd: data ISO
    • createdAt: data ISO

Listar Assinaturas (List Subscriptions)

Lista todas as assinaturas da empresa.

• URL: /subscriptions
• Método: GET
• Parâmetros (Consulta):
  • customerEmail: (Opcional) Filtrar por e-mail do cliente.
  • status: (Opcional) Filtrar por status.
  • planId: (Opcional) Filtrar por ID do plano.
• Resposta (200 OK):
  • success: true
  • data: Array de objetos de Assinatura.

Atualizar Assinatura (Update Subscription)

Atualiza o status de uma assinatura (cancel, pause, resume).

• URL: /subscriptions/{id}
• Método: PATCH
• Parâmetros:
  • id (caminho): UUID da assinatura
• Corpo da Solicitação:

Campo	Tipo	Obrigatório	Descrição
action	string	Sim	Um dos seguintes: cancel, pause, resume.

• Resposta (200 OK):
  • id: UUID
  • status: ACTIVE, CANCELED, PAST_DUE, PAUSED
  • currentPeriodEnd: data ISO

Erros

A API usa códigos de status HTTP padrão para indicar sucesso ou falha. As respostas de erro seguem este formato:

{
  "error": {
    "message": "Mensagem de erro legível por humanos",
    "code": "CODIGO_LEGIVEL_POR_MAQUINA"
  }
}

Códigos de Erro Comuns:

• UNAUTHORIZED
• NOT_FOUND
• MISSING_FIELDS
• WALLET_NOT_FOUND
• CURRENCY_MISMATCH
• PAYMENT_FAILED
• INTERNAL_ERROR