Charge from a channel

These endpoints are implemented and verified against the DSI sandbox (payment created with a real link, and status closed by webhook). The final public callback host is still pending for production, which is why the group is still tagged Coming soon.

A channel (POS, kiosk, web, or app) uses these endpoints to charge through PayBridge. The channel only sends the transaction data (order, amount, method, storeId, terminalId); PayBridge resolves the provider, creates the payment, and returns a payment link for the channel to show the customer. The final status arrives through the status webhook. The merchant configuration (credentials, methods, terminals) already lives in the provider via the config sync, which is why the charge travels lean.

Authentication

string

required

A vendor-scoped Fire API key with the paybridge:charge scope. accountId and vendorId are derived from the key; a key without a vendor returns 403.

Every response is wrapped in { "success": true, "data": { … } }.

Charges and attempts

Charge (intent)

The charge for one order: total amount, currency, store, terminal, and channel. The channel creates it once.

Attempt

Each payment attempt inside the charge. It takes a slot: one slot per method in a split payment, and a new attempt in the same slot when you retry.

Charge statuses:

Status	Meaning
`processing`	An attempt is under way, with no link for the customer yet.
`requires_action`	A payment link is waiting for the customer.
`partially_paid`	Part of the total was collected (split payment in progress).
`succeeded`	The full amount was collected.
`failed`	Every attempt failed and none is active.
`canceled`	Every attempt was canceled.
`pending` / `reversed`	Reserved (no attempts yet / full reversal).

Attempt statuses:

Status	Meaning
`created`	Recorded in Fire, not sent to the provider yet.
`requires_redirect`	The provider returned the `paymentLink`: show it to the customer.
`succeeded`	Payment approved (confirmed by the webhook).
`failed`	The payment could not be created or the provider rejected it; the reason is in `errorDescription`.
`canceled`	The attempt was canceled (unpaid or expired link).
`solving`	Refund in progress, waiting for the provider to confirm.
`refunded`	Refund confirmed.
`processing` / `requires_action`	Reserved.

Flow

Create the charge

The channel calls POST /intents with the order, amount, method, and its storeId/terminalId. PayBridge creates the payment at the provider and returns the paymentLink in the first attempt.

Show the link

The channel shows the paymentLink (redirect, QR, or iframe) for the customer to pay.

Learn the result

Fire receives the provider status through the webhook and updates the attempt and the charge. The channel reads it with GET /intents/{intentId}.

Close the case

If the customer doesn’t pay, cancel the attempt. If the payment is already approved, refund it. If it fails or money is missing, add another attempt with POST /intents/{intentId}/pay.

Endpoints

Operation	Method	Endpoint
Create charge	`POST`	`/api/v1/external/paybridge/intents`
Get charge	`GET`	`/api/v1/external/paybridge/intents/{intentId}`
Add attempt (split or retry)	`POST`	`/api/v1/external/paybridge/intents/{intentId}/pay`
Cancel attempt	`POST`	`/api/v1/external/paybridge/attempts/{attemptId}/cancel`
Refund attempt	`POST`	`/api/v1/external/paybridge/attempts/{attemptId}/refund`

Create charge

POST /api/v1/external/paybridge/intents

string

required

The order id in the channel’s system (max. 80 characters). This is the idempotency key: sending the same value again returns the existing charge instead of duplicating it.

string

required

Payment method code in Fire (for example deuna, rutpay). It must be active in the catalog, otherwise the call returns 400.

number

required

Total amount to charge, in the currency’s major unit (for example 19.90).

string

required

Three-letter ISO 4217 currency (USD, CLP, COP, ARS, VES, BRL).

string

required

UUID of the store in Fire. It travels to the provider as branchOffice.

string

required

Id of the POS terminal or the kiosk device. It travels to the provider as pointOfSale.

string

required

Channel that originates the charge: POS, KIOSK, WEB, or APP.

string

Country of the charge (ISO alpha-2). You can omit it when the method belongs to a single country: Fire derives it. For multi-country methods it is required; without it the attempt ends up failed because the country connection can’t be resolved.

object

Optional payer data. It is forwarded to the provider when required.

Show customer

string

Full name; it is split into first and last name.

string

Tax id, depending on the country.

string

object

The charge with all its attempts.

Show intent

string

UUID of the charge in Fire.

string

Charge status.

number

Sum of the approved attempts.

string

string | null

string

string | null

Reserved; always null today.

object[]

Show attempt

string

number

Split-payment slot (1, 2, 3…).

number

Retry number inside the slot.

string

Attempt status.

number

string

string | null

Link to show the customer.

string | null

Failure reason, if any.

{
  "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
        }
      ]
    }
  }
}

If the provider rejects the payment creation, the response is still 201: the charge exists and its attempt is failed with the reason in errorDescription. Check the attempt status, not just the HTTP code.

Get charge

GET /api/v1/external/paybridge/intents/{intentId} Returns the local status of the charge and all its attempts. It does not call the provider: the status is kept up to date by the webhook.

string

required

UUID of the charge returned when it was created. You only see charges of the API key’s account; a charge from another account returns 404.

object

The same object returned by the creation call.

{
  "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
        }
      ]
    }
  }
}

Add an attempt

POST /api/v1/external/paybridge/intents/{intentId}/pay It covers two cases: retrying a method that failed and split payments (several methods on the same order).

string

required

UUID of the charge.

string

required

Method for the new attempt.

number

Amount of the attempt. If omitted, it uses what’s left (amountTotal - amountPaid).

number

Slot the attempt belongs to. If omitted, a new slot is opened (split payment). To retry, send the slot of the attempt that failed. A slot with an active attempt returns 400.

object

The updated charge, with the new attempt inside attempts.

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

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

A closed charge (succeeded, canceled, or reversed) doesn’t accept new attempts: it returns 400.

Cancel attempt

POST /api/v1/external/paybridge/attempts/{attemptId}/cancel Cancels an active attempt whose link hasn’t been paid yet (or expired).

string

required

Id of the attempt to cancel.

object

The updated charge; the attempt becomes canceled.

The provider only accepts the cancellation once the link is already waiting for payment (waitingPayment). A freshly created attempt usually answers “cancellation does not apply”: in that case Fire does not mark the attempt as canceled and returns the error, so a payment that is still alive on the provider side isn’t treated as canceled.

Refund attempt

POST /api/v1/external/paybridge/attempts/{attemptId}/refund Refunds an already approved attempt (succeeded).

string

required

Id of the approved attempt.

object

The updated charge; the attempt moves to solving until the provider confirms.

Full refunds only. The provider doesn’t support partial amounts: sending amount in the body returns 400. The refund is asynchronous — the attempt stays in solving and becomes refunded when the refundPayment webhook arrives (or stays in solving with the reason if refundFailed arrives).

Errors

HTTP	`error`	When
`400`	`VALIDATION_ERROR`	Invalid body (missing field, `storeId` is not a UUID, 4-letter currency…).
`400`	`DOMAIN_ERROR`	Inactive method, closed charge, slot with an active attempt, partial refund, attempt that can’t be canceled.
`403`	`FORBIDDEN`	API key without the `paybridge:charge` scope or without a vendor.
`404`	`NOT_FOUND`	The charge or the attempt doesn’t exist, or belongs to another account.

Every error carries { "success": false, "error": "…", "message": "…" }.

Status webhook

How the provider tells Fire that the payment was approved, canceled, or refunded.

Config sync to DSI

How the merchant configuration reaches the provider so the charge stays lean.

Methods supported per country

Which methods each country can charge, and with which code.

Method availability

Which method is on in each store, device, and channel.

​Authentication

​Charges and attempts

Charge (intent)

Attempt

​Flow

​Endpoints

​Create charge

​Get charge

​Add an attempt

​Cancel attempt

​Refund attempt

​Errors

​Related

Status webhook

Config sync to DSI

Methods supported per country

Method availability

Authentication

Charges and attempts

Flow

Endpoints

Create charge

Get charge

Add an attempt

Cancel attempt

Refund attempt

Errors

Related