Get Payout

This operation retrieves the full payout information using either the internal payout ID or the merchant-defined reference. It is useful for reconciliation, custom error-handling flows, or to verify webhook delivery.

💡
Always rely on webhook notifications to track final payout statuses.
The Get endpoints should only be used in case of inconsistencies or for manual recovery flows.

Available Endpoints

Identifier	When to Use	API Reference
`payoutId`	When the Bamboo internal ID is available from the create response or webhook.	Get Payout by ID
`reference`	When using the merchant-defined payout reference.	Get Payout by Reference

Request

Each endpoint requires your private key in the header for authorization.
No request body is required.

Response Parameters

Property	Format	Description
`payoutId`	`integer`	Internal identification of the payout.
`reference`	`string`	Identifier defined by the merchant when the payout was created.
`isoCountry`	`string`	ISO code of the destination country, in the format `ISO 3166-1 alpha-2`.
`created`	`date`	Date and time when the payout was created.
`lastUpdate`	`date`	Date and time of the last update to the payout status.
`status`	`integer`	Numeric code of the current payout status. Refer to this article for more details.
`statusDescription`	`string`	Description of the payout status.
`errorCode`	`string`	Internal code representing the failure reason, if any. See possible values in the Reference Page.
`errorDescription`	`string`	Description of the error that caused the payout to fail.
`description`	`string`	Optional description or reason provided during payout creation.
`amount → value`	`number`	Requested payout amount.
`amount → isoCurrency`	`string`	Currency code of the payout amount.
`localAmount`	`object`	Amount in local currency, if conversion was applied. May be `null`.
`exchangeRate`	`numeric`	Conversion rate used for the payout. May be `null` if no FX was applied.
`payee → firstName`	`string`	Recipient’s first name.
`payee → lastName`	`string`	Recipient’s last name.
`payee → companyName`	`string`	Company name, used only for business payouts. May be empty for individuals.
`payee → email`	`string`	Recipient’s email address.
`payee → phone`	`string`	Recipient’s phone number.
`payee → location → city`	`string`	City of the recipient.
`payee → location → address`	`string`	Street address of the recipient.
`payee → location → zipCode`	`string`	Postal code of the recipient.
`payee → document → number`	`string`	Identification number of the recipient.
`payee → document → type`	`string`	Type of document. See Country considerations for more information.

Response Example

{
    "payoutId": 204307526961955232,
    "reference": "ARI-904",
    "isoCountry": "BG",
    "created": "2025-07-17T18:45:12.4807443Z",
    "lastUpdate": "2025-07-17T18:45:12.4808228Z",
    "status": 7,
    "statusDescription": "Held",
    "errorCode": "null",
    "errorDescription": "null",
    "amount": {
        "value": 5.08,
        "isoCurrency": "USD"
    },
    "localAmount": null,
    "exchangeRate": null,
    "payee": {
        "firstName": "Ari",
        "lastName": "Carba",
        "email": "",
        "phone": "099999999",
        "location": {
            "city": "city",
            "address": "address",
            "zipCode": "zip"
        },
        "document": {
            "number": "ABC123456789",
            "type": "BULSTAT"
        }
    },
    "description": "string"
}

Next steps

Get by ID

Explore real response examples and test with your staging credentials.

Get by Reference

Retrieve a payout using your merchant-defined reference.

Webhook Notifications

Learn how to receive final status updates automatically.

Payout Error Codes

Understand common reasons for declined or rejected payouts.