Pular para o conteúdo principal

​
Visão Geral

Consulta o status atualizado de um pagamento de boleto diretamente no provedor e sincroniza automaticamente com o banco de dados local. Útil para:
  • Verificar o status atual do pagamento
  • Sincronizar status em caso de webhook perdido
  • Obter informações detalhadas do provedor
Este endpoint consulta o status em tempo real no provedor de pagamento e atualiza automaticamente o banco de dados local se houver divergência.

​
Parâmetros da Requisição

​
id
string
required
ID do pagamento (UUID) retornado ao criar o pagamentoExemplo: 550e8400-e29b-41d4-a716-446655440000

​
Resposta de Sucesso

​
id
string
ID único do pagamento (UUID)
​
externalId
string
Identificador externo fornecido na criação (se foi fornecido)
​
status
string
Status atual do pagamento no sistema localValores possíveis:
  • PENDING: Pagamento em processamento
  • PAID: Pagamento confirmado
  • CANCELED: Pagamento cancelado
  • REFUND_OCCURRENCE: Ocorrência de estorno
​
statusProvider
string
Status retornado pelo provedor de pagamentoValores possíveis:
  • CONFIRMED: Pagamento confirmado
  • PROCESSING: Em processamento
  • ERROR: Erro no pagamento
​
amount
number
Valor do pagamento em reais
​
paymentDate
string
Data/hora em que o pagamento foi efetivado (formato ISO 8601)Retorna null se o pagamento ainda não foi confirmado.
​
updatedAt
string
Data/hora da última atualização do status (formato ISO 8601)
​
providerData
object
Dados adicionais retornados pelo provedor de pagamento

​
Exemplo de Requisição

cURL
curl -X GET https://api-gateway.firebanking.com.br/bank-slip/v1/payment/withdraw/550e8400-e29b-41d4-a716-446655440000/status \
  -H "x-api-key: YOUR_API_KEY"
JavaScript
const response = await fetch('https://api-gateway.firebanking.com.br/bank-slip/v1/payment/withdraw/550e8400-e29b-41d4-a716-446655440000/status', {
  headers: {
    'x-api-key': 'YOUR_API_KEY'
  }
});

const data = await response.json();
Python
import requests

response = requests.get(
    'https://api-gateway.firebanking.com.br/bank-slip/v1/payment/withdraw/550e8400-e29b-41d4-a716-446655440000/status',
    headers={
        'x-api-key': 'YOUR_API_KEY'
    }
)

data = response.json()

​
Exemplo de Resposta

​
Pagamento Confirmado

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "externalId": "PAY-2024-001",
  "status": "PAID",
  "statusProvider": "CONFIRMED",
  "amount": 152.50,
  "paymentDate": "2024-01-10T14:30:00.000Z",
  "updatedAt": "2024-01-10T14:30:15.000Z",
  "providerData": {
    "account": "12345-6",
    "clientRequestId": "PAY-2024-001",
    "errorCode": null,
    "message": "Payment processed successfully"
  }
}

​
Pagamento Pendente

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "externalId": "PAY-2024-001",
  "status": "PENDING",
  "statusProvider": "PROCESSING",
  "amount": 152.50,
  "paymentDate": null,
  "updatedAt": "2024-01-10T14:25:00.000Z",
  "providerData": {
    "account": "12345-6",
    "clientRequestId": "PAY-2024-001",
    "errorCode": null,
    "message": "Payment is being processed"
  }
}

​
Pagamento com Erro

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "externalId": "PAY-2024-001",
  "status": "CANCELED",
  "statusProvider": "ERROR",
  "amount": 152.50,
  "paymentDate": null,
  "updatedAt": "2024-01-10T14:26:00.000Z",
  "providerData": {
    "account": "12345-6",
    "clientRequestId": "PAY-2024-001",
    "errorCode": "CBE001",
    "message": "Bank slip already paid"
  }
}

​
Códigos de Resposta

​
200
success
Status consultado com sucesso
​
404
error
Pagamento não encontradoO ID fornecido não existe ou não pertence à conta autenticada.
​
401
error
API key inválida ou ausente
​
500
error
Erro interno do servidor

​
Sincronização Automática

Este endpoint implementa sincronização inteligente de status:
  1. Consulta o status local no banco de dados
  2. Consulta o status no provedor de pagamento em tempo real
  3. Se houver divergência e o status local não for final (PAID, CANCELED):
    • Atualiza o status local automaticamente
    • Registra a sincronização nos logs
  4. Retorna o status atualizado

​
Estados Finais (não sincronizados)

Os seguintes status são considerados finais e não serão sobrescritos:
  • PAID: Pagamento confirmado
  • CANCELED: Pagamento cancelado
  • REFUND_OCCURRENCE: Estorno processado
Fail-safe: Se a consulta no provedor falhar, o endpoint retorna o status local sem erro, garantindo que você sempre tenha uma resposta.

​
Casos de Uso

​
Verificar status após criação

// 1. Criar pagamento
const createResponse = await createPayment(barcode);
const paymentId = createResponse.id;

// 2. Aguardar alguns segundos
await sleep(5000);

// 3. Consultar status
const statusResponse = await getPaymentStatus(paymentId);

if (statusResponse.status === 'PAID') {
  console.log('Pagamento confirmado!');
} else if (statusResponse.status === 'PENDING') {
  console.log('Ainda processando...');
}

​
Sincronizar após webhook perdido

Se um webhook não for recebido, você pode usar este endpoint para forçar a sincronização: 
const statusResponse = await getPaymentStatus(paymentId);

// O status foi automaticamente sincronizado com o provedor
console.log('Status atualizado:', statusResponse.status);

​
Mapeamento de Status

Status ProvedorStatus InternoDescrição
CONFIRMEDPAIDPagamento confirmado com sucesso
PROCESSINGPENDINGPagamento em processamento
ERRORCANCELEDErro no processamento

​
Próximos Passos

Dica: Use este endpoint quando precisar verificar o status imediatamente, sem depender de webhooks. Ideal para interfaces de usuário ou validações em tempo real.