Transaction Notification

The Transaction Webhook notifies merchants asynchronously about the final status of any transaction processed through Bamboo, including purchases and refunds. It provides complete details for reconciliation, auditing, and post-settlement analysis.

Notification Parameters

The data structure is modular. Below you will find the parameter breakdown separated by objects.

Parameter	Type	Description
`TransactionId`	Number	Unique transaction identifier within Bamboo Payments.
`UniqueId`	String	Unique alphanumeric identifier generated by the merchant to identify the transaction and prevent double charging.
`Order`	String	Merchant's internal reference or purchase order ID.
`TransactionType`	String	Type of operation (e.g., `PURCHASE`, `REFUND`).
`Status`	String	Core status string (e.g., `APPROVED`, `PENDING`, `REJECTED`).
`Description`	String	Optional description provided by the merchant or returned by the acquirer/processor.
`ApprovalCode`	String	Authorization code provided by the processing network or bank.
`Amount`	Number	Total transaction amount represented in minor units (e.g., cents, without decimal separators. E.g., `1000` represents `10.00`).
`Currency`	String	Three-letter ISO 4217 currency code (e.g., `ARS`, `USD`, `CLP`).
`Installments`	Number	Number of installments chosen for the transaction (cards).
`MetadataOut`	Object	Key-value dictionary containing dynamic response properties returned by the local payment provider.
`AdditionalData`	Object	Key-value store containing dynamic parameters (varies based on country and method).
`ErrorCode`	String	Error code alphanumeric representation if the transaction fails.
`Created`	String	ISO 8601 timestamp (`YYYY-MM-DDTHH:mm:ss.SSSZ`) indicating transaction creation.
`UrlNotify`	String	The target merchant URL where this notification is delivered.
`TargetCountryIso`	String	Two-letter ISO country code where processing took place (e.g., `AR`, `MX`, `CL`).
`Customer`	Object	Contains identity and contact information of the end-buyer. See Customer Object.
`PaymentMedia`	Object	Contains technical properties of the payment vehicle used. See PaymentMedia Object.
`VirtualAccount`	Object	Optional. Included only if processed via bank transfer to a dynamic virtual account. See VirtualAccount Object.

Customer Object

Parameter	Type	Description
`CustomerId`	Number	Unique identifier for the customer record in Bamboo.
`Email`	String	Customer's primary contact email address.
`DocumentAbbreviation`	String	Localized acronym for the identification document type (e.g., `RUT`, `CPF`, `CUIT`).
`DocNumber`	String	Alphanumeric string representing the customer's legal identification number.
`FirstName`	String	Given name(s) of the customer.
`LastName`	String	Family name(s) of the customer.

PaymentMedia Object

Parameter	Type	Description
`PaymentMediaType`	String	Broad categorization of the funding vehicle (e.g., `CreditCard`, `DebitCard`, `Cash`, `Transfer`).
`Brand`	String	Brand name or provider network processing the fund (e.g., `Visa`, `MasterCard`, `OXXO`, `BIND`).
`IssuerBank`	String	Name of the issuing bank entity (applicable mostly for cards).
`Bin`	String	The first 6 digits of the card number (Bank Identification Number).
`Last4`	String	The final 4 digits of the card number.
`Owner`	String	The cardholder's full name exactly as printed on the card.

VirtualAccount Object

Parameter	Type	Description
`VirtualAccountId`	Number	Internal platform ID managing this specific virtual ledger/sub-account.
`Status`	String	Lifecycle status of the virtual account when processing (e.g., `ACTIVE`).
`OwnershipModel`	String	Defines entity alignment for compliance frameworks (`BAMBOO_OWNED`, `MERCHANT_OWNED`, `NAMED_ACCOUNT`).
`UniqueId`	String	Custom tracking reference assigned by the merchant during deployment.
`PaymentInstrument`	Object	Banking network routing properties. See PaymentInstrument Object.
`AccountOwner`	Object	Legal identity backing the specific sub-account ledger. See AccountOwner Object.

PaymentInstrument Object

Parameter	Type	Description
`Type`	String	National banking standard format tag (e.g., `CLABE`, `CVU`, `CBU`).
`BankAccount`	String	Complete unmasked routing string, CBU, or account code receiving the transfer.
`BankName`	String	Name or short acronym of the local custodian clearing bank (e.g., `STP`, `BIND`).
`BankAccountHolder`	String	Registered descriptor name of the account in the banking network interface.

AccountOwner Object

Parameter	Type	Description
`Type`	String	Classification of entity type owning the balance (`COMPANY` or `INDIVIDUAL`).
`BusinessName`	String	Corporate registration name (populated only if `Type` is `COMPANY`).
`FirstName`	String	Given name of the owner (populated only if `Type` is `INDIVIDUAL`).
`LastName`	String	Surname of the owner (populated only if `Type` is `INDIVIDUAL`).
`DocumentNumber`	String	Fiscal registration string or document digits (e.g., `CUIT`, `RFC`, `RUT`).
`DocumentType`	String	Country-specific category tag for the provided fiscal document.
`Email`	String	Registered notification email address linked to the sub-merchant owner.
`PhoneNumber`	String	Contact phone string conforming to international E.164 standardization.

Response Examples

Select the corresponding tab below to view the payload structure based on the payment method used for the transaction.

{
  "TransactionId": 379245,
  "TransactionType": "Purchase",
  "Status": "Rejected",
  "ErrorCode": "TR301",
  "Amount": 5000,
  "Currency": "UYU",
  "Installments": "1",
  "UniqueId": "123456",
  "Order": "1",
  "Description": "Description",
  "UrlNotify": "https://dummystore.com/checkout/notifications",
  "TargetCountryIso": "UY",
  "Created": "2024-02-07T18:10:45.667",
  "MetadataOut": { },
  "Customer": {
    "CustomerId": 321559,
    "Email": "[email protected]",
    "DocumentAbbreviation": "RUT.UY",
    "DocNumber": "52960268",
    "LastName": "Cardenas Contreras",
    "FirstName": "Rocio"
  },
  "PaymentMedia": {
    "PaymentMediaType": "CreditCard",
    "Brand": "MasterCard",
    "IssuerBank": "ADMINISTRADORA DE TARJETAS DE CREDITO, (A.T.C.), S.A.",
    "Bin": "558900",
    "Last4": "0001",
    "Owner": "JOHN DOE"
  }
}

{
    "TransactionId": 148906700189999616,
    "TransactionType": "Refund",
    "Status": "Approved",
    "Description": "Automation Test",
    "ApprovalCode": "10",
    "AdditionalData": null,
    "ErrorCode": null,
    "Created": "2025-02-14T21:42:03.88",
    "UrlNotify": null,
    "TargetCountryIso": "CO",
    "Customer": {
        "CustomerId": 148905131889422016,
        "Email": "[email protected]",
        "DocumentAbbreviation": "CC.CO",
        "DocNumber": "1234567890",
        "LastName": "Torres",
        "FirstName": "Lisseth"
    },
    "PaymentMedia": {
        "PaymentMediaType": "BankTransfer",
        "Brand": "PseAvanza",
        "IssuerBank": null,
        "Bin": null,
        "Last4": null,
        "Owner": null
    },
    "Amount": -2058800,
    "Installments": 1,
    "Currency": "COP",
    "MetadataOut": {
        "RefundBankAccountNumber": "132132********2132",
        "RefundBankId": "1063",
        "RefundBankName": "BANCO FINANDINA S.A.",
        "RefundBankAccountType": "Saving"
    }
}

{
  "TransactionId": 326050278602283616,
  "TransactionType": "PURCHASE",
  "Status": "APPROVED",
  "Description": null,
  "ApprovalCode": "AUTH123",
  "AdditionalData": null,
  "ErrorCode": null,
  "Created": "2026-06-18T17:27:29.1724957Z",
  "UrlNotify": null,
  "TargetCountryIso": "MX",
  "Amount": 1769,
  "Currency": "MXN",
  "Customer": {
    "CustomerId": 326050278602283616,
    "Email": "[email protected]",
    "DocumentAbbreviation": "RFC.MX",
    "DocNumber": "12345678",
    "LastName": "Doe",
    "FirstName": "John"
  },
  "PaymentMedia": {
    "PaymentMediaType": "BankTransfer",
    "Brand": "SPEI",
  },
  "VirtualAccount": {
    "VirtualAccountId": 325330756438165568,
    "Status": "ACTIVE",
    "OwnershipModel": "BAMBOO_OWNED",
    "UniqueId": "ref-500224",
    "PaymentInstrument": {
      "Type": "CLABE",
      "BankAccount": "31182538978110004784",
      "BankName": "STP",
      "BankAccountHolder": "ACME Corp - Bamboo Payments"
    },
    "AccountOwner": {
      "Type": "COMPANY",
      "BusinessName": "Acme Corp 2",
      "FirstName": null,
      "LastName": null,
      "DocumentNumber": "123456789",
      "DocumentType": "RUT",
      "Email": "[email protected]",
      "PhoneNumber": "+59899123456"
    }
  }
}

Response Expected

The merchant’s webhook endpoint must return HTTP 200 (OK) to confirm that the notification was successfully received and processed. If Bamboo receives any other status code or no response, the notification will be retried according to the Retry Policy.

Response Code	Meaning
`200`	Notification successfully received and processed.
`4xx`	Client-side error (invalid endpoint, payload rejection, or failed signature validation).
`5xx`	Temporary server error. Bamboo will retry the notification automatically.

Next Steps

Webhook Overview

Learn about authentication, retry policy, and webhook configuration for Payins.

Chargeback Webhook

Explore how chargeback notifications are structured and delivered.

Error Codes

Understand possible error responses and how to handle them.