Bre-B transaction

Bre-B deposits don't use a standard transaction initiation request. Instead, you provision a reusable Bre-B Llave once per shopper, display the brebKey from that response to the shopper as the destination they should pay to, and the shopper transfers funds from their own banking app. PXP creates the deposit when the processor notifies it, and sends you the breb-transaction-order-executed webhook as your first and authoritative notice of the deposit.

You can submit a Bre-B payout in these ways:

• Payout (withdrawal), new Llave: Create a pay-by-bank transaction with apmProvider set to Breb and intent set to Payout, and supply bankAccountNumber with the provisioned Llave (including the @ prefix). Capture fundingData.payByBank.gatewayTokenId from the response to reuse the destination later.
• Payout (withdrawal), stored Llave: Create a payout and supply gatewaytokenid from an earlier accepted payout instead of resending the Llave.

Bre-B supports COP only. Provision and payout requests use Colombian shopper identity details (country / countryCode CO in the examples below). Treat merchant webhooks as the authoritative final outcome. There's no hosted redirect step for Bre-B, and Bre-B doesn't support alias updates. Learn more about webhooks.

Use the following request to provision a reusable Bre-B Llave for a shopper. The call creates no transaction. Set apmProvider to Breb.

{
  "merchant": "MERCHANT-1",
  "site": "SITE-1",
  "apmProvider": "Breb",
  "shopperId": "Shopper_CO_01",
  "userName": "juan.perez",
  "email": "juan.perez@example.com",
  "firstName": "Juan",
  "lastName": "Perez",
  "country": "CO",
  "documentType": "IdentityDocument",
  "documentNumber": "1234567890"
}

If your request is successful, you'll receive a 200 response with status set to Success. Show the brebKey to the shopper. isEligibleForWithdrawal is always returned: it's false immediately after provision and becomes true after a successful pay-in. On failure, status is Error and stateData carries the mapped fault detail. brebKey and provisionedAt are omitted when they don't apply.

{
  "transactionContextId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "brebKey": "@pxpshopper01",
  "provisionedAt": "2026-08-28T12:00:00Z",
  "isEligibleForWithdrawal": false,
  "status": "Success"
}

After you display the Llave, don't call any API when the shopper deposits. Wait for the breb-transaction-order-executed webhook, which creates and confirms the deposit. Deposit notifications may have a null merchantTransactionId because there was no merchant create call. Learn more about webhooks.

{
  "merchant": "MERCHANT-1",
  "site": "SITE-1",
  "merchantTransactionId": "BREB-PAYOUT-001",
  "merchantTransactionDate": "2026-08-28T12:00:00Z",
  "transactionMethod": {
    "intent": "Payout",
    "entryType": "Ecom",
    "fundingType": "PayByBank"
  },
  "fundingData": {
    "payByBank": {
      "apmProvider": "Breb",
      "bankAccountNumber": "@pxpshopper01"
    }
  },
  "amounts": {
    "transaction": 100.00,
    "currencyCode": "COP"
  },
  "shopper": {
    "id": "Shopper_CO_01",
    "firstName": "Juan",
    "lastName": "Perez",
    "email": "juan.perez@example.com",
    "countryCode": "CO",
    "documentType": "IdentityDocument",
    "documentNumber": "1234567890"
  }
}

If your request is successful, you'll receive a 200 response. For a successful Bre-B payout initiation, expect a Pending state with no redirectUrl, plus fundingData.payByBank.paymentId and fundingData.payByBank.gatewayTokenId.

The final outcome is delivered by a Bre-B merchant webhook (e.g., breb-transaction-order-executed). See Webhooks below.

Always use the systemTransactionId for later PXP API calls against the same transaction. Provider payment identifiers are for reconciliation and support only.

{
  "state": "Pending",
  "systemTransactionId": "1ed768bb-e88a-4636-91ae-67927ccbb02b",
  "merchantTransactionId": "BREB-PAYOUT-001",
  "fundingData": {
    "payByBank": {
      "apmProvider": "Breb",
      "paymentId": "7c1d8e32-4a6b-4f9c-b2d3-1e2f3a4b5c6d",
      "gatewayTokenId": "b6e2f1a4-c3d8-4f7a-b1e9-d2c3f4a5b6c7"
    }
  }
}

Treat Bre-B merchant webhooks as the authoritative final outcome for deposits, payouts, and refunds. Don't treat the transaction initiation response alone as settlement for a payout.

Use transactionMethod.intent to tell deposits (Purchase) and payouts (Payout) apart when they share the same event code. For deposits, breb-transaction-order-executed is your first notice of the transaction, so merchantTransactionId may be null. Correlate deposits by using systemTransactionId and the shopper's Bre-B context.

The following event codes apply to Bre-B:

{
  "eventDate": "2026-08-28T12:00:00.0000000Z",
  "eventCategory": "transaction",
  "eventOwner": {
    "merchantGroup": "merchant-group-1",
    "merchant": "MERCHANT-1",
    "site": "SITE-1"
  },
  "eventData": {
    "eventCode": "breb-transaction-order-executed",
    "state": "Authorised",
    "stateData": {
      "code": "APM003",
      "message": "Payment authorised"
    },
    "amounts": {
      "transaction": 100,
      "currencyCode": "COP"
    },
    "merchant": "MERCHANT-1",
    "site": "SITE-1",
    "transactionMethod": {
      "intent": "Purchase",
      "entryType": "Ecom",
      "fundingType": "PayByBank"
    },
    "fundingData": {
      "payByBank": { … }
    },
    "providerResponse": {
      "provider": "Breb",
      "providerTransactionStatus": "Authorised",
      "providerResponseCode": "EXECUTED",
      "providerResponseMessage": "Payment authorised"
    },
    "merchantTransactionId": null,
    "systemTransactionId": "1ed768bb-e88a-4636-91ae-67927ccbb02b"
  }
}

{
  "eventDate": "2026-08-28T12:05:00.0000000Z",
  "eventCategory": "transaction",
  "eventOwner": {
    "merchantGroup": "merchant-group-1",
    "merchant": "MERCHANT-1",
    "site": "SITE-1"
  },
  "eventData": {
    "eventCode": "breb-transaction-order-executed",
    "state": "Authorised",
    "stateData": {
      "code": "APM003",
      "message": "Payment authorised"
    },
    "amounts": {
      "transaction": 100,
      "currencyCode": "COP"
    },
    "merchant": "MERCHANT-1",
    "site": "SITE-1",
    "transactionMethod": {
      "intent": "Payout",
      "entryType": "Ecom",
      "fundingType": "PayByBank"
    },
    "fundingData": {
      "payByBank": { … }
    },
    "providerResponse": {
      "provider": "Breb",
      "providerTransactionStatus": "Authorised",
      "providerResponseCode": "EXECUTED",
      "providerResponseMessage": "Payment authorised"
    },
    "merchantTransactionId": "BREB-PAYOUT-001",
    "systemTransactionId": "1ed768bb-e88a-4636-91ae-67927ccbb02b"
  }
}