Cobrar a partir de um canal

Estes endpoints já estão implementados e verificados contra o sandbox da DSI (criação do pagamento com link real e fechamento do status por webhook). Falta o host público definitivo dos callbacks para operar em produção; por isso o grupo continua marcado como Em breve.

Um canal (POS, quiosque, web ou app) usa estes endpoints para cobrar pelo PayBridge. O canal envia apenas os dados da transação (pedido, valor, método, storeId, terminalId); o PayBridge resolve o provedor, cria o pagamento e devolve um link de pagamento que o canal mostra ao cliente. O status final chega pelo webhook de status. A configuração do comércio (credenciais, métodos, terminais) já vive no provedor via o config sync, por isso a cobrança viaja lean.

Autenticação

string

obrigatório

API key do Fire vendor-scoped com o scope paybridge:charge. O accountId e o vendorId são derivados da key; uma key sem vendor responde 403.

Todas as respostas vêm envolvidas em { "success": true, "data": { … } }.

Cobrança e tentativas

Cobrança (intent)

A cobrança de um pedido: valor total, moeda, loja, terminal e canal. O canal cria uma só vez.

Tentativa (attempt)

Cada tentativa de pagamento dentro da cobrança. Ocupa uma vaga (slot): uma vaga por método no pagamento misto, e uma tentativa nova na mesma vaga quando se repete.

Status da cobrança:

Status	Significado
`processing`	Há uma tentativa em andamento, ainda sem link para o cliente.
`requires_action`	Há um link de pagamento esperando o cliente.
`partially_paid`	Parte do total foi cobrada (pagamento misto em andamento).
`succeeded`	O total foi cobrado.
`failed`	Todas as tentativas falharam e nenhuma está ativa.
`canceled`	Todas as tentativas foram canceladas.
`pending` / `reversed`	Reservados (sem tentativas ainda / reversão total).

Status da tentativa:

Status	Significado
`created`	Registrada no Fire, ainda sem envio ao provedor.
`requires_redirect`	O provedor devolveu o `paymentLink`: é preciso mostrá-lo ao cliente.
`succeeded`	Pagamento aprovado (confirmado pelo webhook).
`failed`	Não foi possível criar o pagamento ou o provedor recusou; o motivo vai em `errorDescription`.
`canceled`	A tentativa foi cancelada (link sem pagar ou vencido).
`solving`	Reembolso em andamento, aguardando a confirmação do provedor.
`refunded`	Reembolso confirmado.
`processing` / `requires_action`	Reservados.

Fluxo

Criar a cobrança

O canal chama POST /intents com o pedido, o valor, o método e seu storeId/terminalId. O PayBridge cria o pagamento no provedor e devolve o paymentLink na primeira tentativa.

Mostrar o link

O canal mostra o paymentLink (redirect, QR ou iframe) para o cliente pagar.

Saber o resultado

O Fire recebe o status do provedor por webhook e atualiza a tentativa e a cobrança. O canal consulta com GET /intents/{intentId}.

Fechar o caso

Se o cliente não pagar, cancele a tentativa. Se o pagamento já está aprovado, reembolse. Se falhar ou faltar valor, adicione outra tentativa com POST /intents/{intentId}/pay.

Endpoints

Operação	Método	Endpoint
Criar cobrança	`POST`	`/api/v1/external/paybridge/intents`
Consultar cobrança	`GET`	`/api/v1/external/paybridge/intents/{intentId}`
Adicionar tentativa (misto ou repetição)	`POST`	`/api/v1/external/paybridge/intents/{intentId}/pay`
Cancelar tentativa	`POST`	`/api/v1/external/paybridge/attempts/{attemptId}/cancel`
Reembolsar tentativa	`POST`	`/api/v1/external/paybridge/attempts/{attemptId}/refund`

Criar cobrança

POST /api/v1/external/paybridge/intents

string

obrigatório

Identificador do pedido no sistema do canal (máx. 80 caracteres). É a chave de idempotência: repetir o mesmo valor devolve a cobrança já criada, sem duplicá-la.

string

obrigatório

Código do método de pagamento no Fire (por exemplo deuna, rutpay). Precisa estar ativo no catálogo; caso contrário responde 400.

number

obrigatório

Valor total a cobrar, na unidade maior da moeda (por exemplo 19.90).

string

obrigatório

Moeda ISO 4217 de 3 letras (USD, CLP, COP, ARS, VES, BRL).

string

obrigatório

UUID da loja no Fire. Viaja ao provedor como branchOffice.

string

obrigatório

Id do terminal POS ou do dispositivo de quiosque. Viaja ao provedor como pointOfSale.

string

obrigatório

Canal que origina a cobrança: POS, KIOSK, WEB ou APP.

string

País da cobrança (ISO alpha-2). Pode ser omitido quando o método pertence a um só país: nesse caso o Fire deriva. Em métodos multipaís é obrigatório; sem ele a tentativa fica failed porque não é possível resolver a conexão do país.

object

Dados opcionais do pagador. São repassados ao provedor quando ele exige.

Mostrar customer

string

Nome completo; é dividido em nome e sobrenome.

string

Identificação fiscal, conforme o país.

string

object

A cobrança com todas as suas tentativas.

Mostrar intent

string

UUID da cobrança no Fire.

string

Status da cobrança.

number

Soma das tentativas aprovadas.

string

string | null

string

string | null

Reservado; hoje sempre null.

object[]

Mostrar attempt

string

number

Vaga do pagamento misto (1, 2, 3…).

number

Nº da repetição dentro da vaga.

string

Status da tentativa.

number

string

string | null

Link para mostrar ao cliente.

string | null

Motivo da falha, se houver.

{
  "externalOrderId": "ORD-2026-001234",
  "methodCode": "deuna",
  "amount": 19.90,
  "currency": "USD",
  "storeId": "3f6c1b6e-52b1-4f0e-9c2a-2b7d5e8a1c40",
  "terminalId": "EC-D0123-POS-1",
  "channel": "KIOSK",
  "country": "EC",
  "customer": { "name": "Ada Lovelace", "email": "ada@example.com", "document": "0912345678" }
}

{
  "success": true,
  "data": {
    "intent": {
      "intentId": "9d1f0b62-3c77-4a1e-9f2b-11a0d8c4e5aa",
      "externalOrderId": "ORD-2026-001234",
      "status": "requires_action",
      "amountTotal": 19.90,
      "amountPaid": 0,
      "currency": "USD",
      "storeId": "3f6c1b6e-52b1-4f0e-9c2a-2b7d5e8a1c40",
      "terminalId": "EC-D0123-POS-1",
      "channel": "KIOSK",
      "expiresAt": null,
      "attempts": [
        {
          "attemptId": "6b2c9a54-8d31-4f77-b0c6-9e3a1f5d2b88",
          "slot": 1,
          "attemptNumber": 1,
          "methodCode": "deuna",
          "status": "requires_redirect",
          "amount": 19.90,
          "currency": "USD",
          "paymentLink": "https://checkout.example.com/deuna/9f8e7d6c",
          "errorDescription": null
        }
      ]
    }
  }
}

Se o provedor recusar a criação do pagamento, a resposta continua sendo 201: a cobrança existe e a tentativa fica em failed com o motivo em errorDescription. Verifique o status da tentativa, não apenas o código HTTP.

Consultar cobrança

GET /api/v1/external/paybridge/intents/{intentId} Devolve o status local da cobrança e todas as suas tentativas. Não chama o provedor: o status é mantido em dia pelo webhook.

string

obrigatório

UUID da cobrança devolvido na criação. Só aparecem as cobranças da conta da API key; a de outra conta responde 404.

object

O mesmo objeto devolvido pela criação.

{
  "success": true,
  "data": {
    "intent": {
      "intentId": "9d1f0b62-3c77-4a1e-9f2b-11a0d8c4e5aa",
      "externalOrderId": "ORD-2026-001234",
      "status": "succeeded",
      "amountTotal": 19.90,
      "amountPaid": 19.90,
      "currency": "USD",
      "storeId": "3f6c1b6e-52b1-4f0e-9c2a-2b7d5e8a1c40",
      "terminalId": "EC-D0123-POS-1",
      "channel": "KIOSK",
      "expiresAt": null,
      "attempts": [
        {
          "attemptId": "6b2c9a54-8d31-4f77-b0c6-9e3a1f5d2b88",
          "slot": 1,
          "attemptNumber": 1,
          "methodCode": "deuna",
          "status": "succeeded",
          "amount": 19.90,
          "currency": "USD",
          "paymentLink": "https://checkout.example.com/deuna/9f8e7d6c",
          "errorDescription": null
        }
      ]
    }
  }
}

Adicionar uma tentativa

POST /api/v1/external/paybridge/intents/{intentId}/pay Serve para dois casos: repetir um método que falhou e pagamento misto (vários métodos no mesmo pedido).

string

obrigatório

UUID da cobrança.

string

obrigatório

Método da nova tentativa.

number

Valor da tentativa. Se omitido, usa o que falta (amountTotal - amountPaid).

number

Vaga à qual a tentativa pertence. Se omitido, abre-se uma vaga nova (pagamento misto). Para repetir, envie o slot da tentativa que falhou. Uma vaga com tentativa ativa responde 400.

object

A cobrança atualizada, com a nova tentativa dentro de attempts.

{ "methodCode": "deuna", "slot": 1 }

{ "methodCode": "rutpay", "amount": 5.00 }

Uma cobrança já fechada (succeeded, canceled ou reversed) não aceita tentativas novas: responde 400.

Cancelar tentativa

POST /api/v1/external/paybridge/attempts/{attemptId}/cancel Cancela uma tentativa ativa cujo link ainda não foi pago (ou venceu).

string

obrigatório

Id da tentativa a cancelar.

object

A cobrança atualizada; a tentativa fica em canceled.

O provedor só aceita o cancelamento quando o link já está aguardando o pagamento (waitingPayment). Uma tentativa recém-criada normalmente responde “não se aplica ao cancelamento”: nesse caso o Fire não marca a tentativa como cancelada e devolve o erro, para não dar como cancelado um pagamento que segue vivo do outro lado.

Reembolsar tentativa

POST /api/v1/external/paybridge/attempts/{attemptId}/refund Reembolsa uma tentativa já aprovada (succeeded).

string

obrigatório

Id da tentativa aprovada.

object

A cobrança atualizada; a tentativa passa a solving até o provedor confirmar.

Apenas reembolso total. O provedor não admite valores parciais: se você enviar amount no body, a resposta é 400. O reembolso é assíncrono — a tentativa fica em solving e passa a refunded quando chega o webhook refundPayment (ou volta a solving com o motivo se chegar refundFailed).

Erros

HTTP	`error`	Quando
`400`	`VALIDATION_ERROR`	Body inválido (falta um campo, `storeId` não é UUID, moeda com 4 letras…).
`400`	`DOMAIN_ERROR`	Método inativo, cobrança fechada, vaga com tentativa ativa, reembolso parcial, tentativa não cancelável.
`403`	`FORBIDDEN`	API key sem o scope `paybridge:charge` ou sem vendor.
`404`	`NOT_FOUND`	A cobrança ou a tentativa não existe, ou é de outra conta.

Todos os erros trazem { "success": false, "error": "…", "message": "…" }.

Relacionado

Webhook de status

Como o provedor avisa o Fire que o pagamento foi aprovado, cancelado ou reembolsado.

Config sync para a DSI

Como a configuração do comércio chega ao provedor para a cobrança ser lean.

Métodos suportados por país

Quais métodos cada país pode cobrar e com qual código.

Disponibilidade de métodos

Qual método está ligado em cada loja, dispositivo e canal.

​Autenticação

​Cobrança e tentativas

Cobrança (intent)

Tentativa (attempt)

​Fluxo

​Endpoints

​Criar cobrança

​Consultar cobrança

​Adicionar uma tentativa

​Cancelar tentativa

​Reembolsar tentativa

​Erros

​Relacionado

Webhook de status

Config sync para a DSI

Métodos suportados por país

Disponibilidade de métodos

Autenticação

Cobrança e tentativas

Fluxo

Endpoints

Criar cobrança

Consultar cobrança

Adicionar uma tentativa

Cancelar tentativa

Reembolsar tentativa

Erros

Relacionado