POST

Redeem payout

Send an eligible payout directly to a recipient's PayPal or Venmo account using a weblink returned by Get Order.

POST/api/Integration/v2/payout/redeem/{weblink}

Use this endpoint only after Get Order returns a payout URL in items[].cards[].cardCode for an eligible payout product.

Redeem payout submits a PayPal or Venmo payout for the weblink token returned by Get Order. PayPal and Venmo use the same endpoint; select the destination wallet in the request body.

Only the client that owns the underlying order can redeem the weblink. If the weblink belongs to another client or cannot be redeemed, Bamboo returns a generic failed-redemption response instead of revealing whether the link exists.

Use this endpoint from your server. Never expose Client Secrets, payout links, or full recipient identifiers in browser code, logs, or public repositories.

This endpoint requires Basic Auth using your API credentials.

Path parameter

The weblink token comes from the final path segment of a payout URL returned in Get Order.

Parameter	Type	Required	Description
`weblink`	string	Yes	Encrypted payout weblink token extracted from items[].cards[].cardCode for an eligible payout product.

Encoding requirement

Preserve the token exactly

Base64 padding in the token must remain URL-encoded as %3D. Do not decode and re-encode the token in a way that turns %3D into %253D.

Request body

Send one wallet value and exactly one recipient identifier. The valid request alternatives are PayPal with recipientEmail, Venmo with recipientEmail, Venmo with recipientPhone, or Venmo with recipientHandle.

PayPal email request

{
  "wallet": "PayPal",
  "recipientEmail": "recipient@example.com"
}

Field	Type	Required	Description
`wallet`	"PayPal" \| "Venmo"	Yes	Selects the payout wallet.
`recipientEmail`	string	Conditional	Recipient email address. Required for PayPal. Allowed for Venmo.
`recipientPhone`	string	Conditional	Recipient phone number. A leading + is optional, followed by 7 to 15 digits. Venmo only.
`recipientHandle`	string	Conditional	Recipient Venmo handle. A leading @ is optional. Use 5 to 30 letters, digits, underscores, or hyphens. Venmo only.

Recipient rules

Exactly one recipient field

Provide one and only one of recipientEmail, recipientPhone, or recipientHandle.

PayPal recipients

PayPal payouts accept recipientEmail only. Phone and handle values are validation errors for PayPal.

Venmo recipients

Venmo payouts accept email, phone, or handle, but still only one recipient identifier per request.

Recipient validation

Bamboo validates email, phone, and Venmo handle format before submitting the payout.

Successful responses

Bamboo returns 200 when the payout has completed and 202 when the payout has been submitted but is still processing.

200 OK

The payout completed.

{
  "transactionId": "fc894d78-e978-46c0-0748-08ded1b0af32",
  "payoutBatchId": "DZGTNDS9H3BWS",
  "isProcessing": false
}

202 Accepted

The payout was submitted and is still processing. Check the payout status endpoint while processing.

{
  "transactionId": "fc894d78-e978-46c0-0748-08ded1b0af32",
  "payoutBatchId": "DZGTNDS9H3BWS",
  "isProcessing": true
}

Field	Type	Description
`transactionId`	string	Bamboo payout transaction identifier returned for this weblink.
`payoutBatchId`	string	PayPal payout batch identifier. Use it to correlate with PayPal reporting.
`isProcessing`	boolean	true when the payout has been accepted but has not reached a final status.

Response handling

200 OK

Treat the payout as completed and store the returned transactionId and payoutBatchId for reconciliation.

202 Accepted

Store the identifiers and check Get payout status while the payout remains in processing.

Examples

Full request and response examples for this endpoint.

Example request

Use this full request as the primary reference for client-side implementation.

# Generate token: echo -n 'YOUR_CLIENT_ID:YOUR_CLIENT_SECRET' | base64

curl --location 'https://api.bamboocardportal.com/api/Integration/v2/payout/redeem/Y1hqd1RiT1EvUXpYZXFtSmZ6dnZ0QjA%3D%3D' \
  --header 'Authorization: Basic YOUR_BASE64_TOKEN' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --data '{
  "wallet": "PayPal",
  "recipientEmail": "recipient@example.com"
}'

Example response

Use this sample payload to validate parsing, field mapping, and downstream handling.

202 Accepted

{
  "transactionId": "fc894d78-e978-46c0-0748-08ded1b0af32",
  "payoutBatchId": "DZGTNDS9H3BWS",
  "isProcessing": true
}

Request examples

Use these request body alternatives with the same POST endpoint and weblink path value.

Venmo email

{
  "wallet": "Venmo",
  "recipientEmail": "recipient@example.com"
}

Venmo phone

{
  "wallet": "Venmo",
  "recipientPhone": "+14155550123"
}

Venmo handle

{
  "wallet": "Venmo",
  "recipientHandle": "@johndoe"
}

Error responses

The redeem endpoint returns validation errors for malformed requests and generic failures for links that cannot be redeemed.

Status	Body	Cause
`400 Bad Request`	"Request body is required."	Missing request body.
`400 Bad Request`	"A valid wallet (PayPal or Venmo) is required."	wallet is missing or is not PayPal or Venmo.
`400 Bad Request`	"Provide exactly one of recipient email, phone, or handle."	Zero recipient fields or more than one recipient field was provided.
`400 Bad Request`	"PayPal payouts support only a recipient email."	wallet is PayPal and recipientPhone or recipientHandle was supplied.
`400 Bad Request`	"Invalid recipient email address."	Malformed email address.
`400 Bad Request`	"Invalid recipient phone number."	Malformed phone number.
`400 Bad Request`	"Invalid recipient user handle."	Malformed Venmo handle.
`400 Bad Request`	"Weblink is disabled"	The weblink has been manually disabled.
`400 Bad Request`	"Payout weblink expired"	The weblink has passed its expiration date.
`400 Bad Request`	"Failed to redeem weblink"	Weblink not found, wrong client ownership, payout rejected, or the card is in a failed state.
`400 Bad Request`	"Recipient ID does not match"	A previous attempt used a different recipient. Re-submit with the same recipient.
`401 Unauthorized`	-	Missing or invalid Authorization header.
`429 Too Many Requests`	-	A concurrent request is in progress for the same endpoint.

Operational notes

Use these rules to make payout redemption safe and repeatable.

Idempotency

Submitting the same weblink token again does not trigger a second payout. Bamboo returns the existing transactionId and payoutBatchId.

Recipient locking

After a payout attempt is associated with one recipient, a later attempt with a different recipient is rejected.

Sandbox

Sandbox accounts send payouts to PayPal's sandbox environment. No real money is transferred, and phone-recipient testing may have limitations.

Sensitive data

Treat payout links and recipient identifiers as sensitive. Avoid logging complete recipient data.

PreviousOrders NextGet payout status

On this page

Try it out

Open the interactive API panel to test this endpoint with your own credentials.

Client ID

Client Secret

Save for this browser

Requests are sent directly from your device. Your IP address must be whitelisted in the client portal API Access page for requests to succeed.

Credentials are stored only in this browser tab session and are removed when the tab is closed. They are never saved to BambooDocs servers.

Production execution can submit a real payout. Use sandbox credentials and test recipient data until you are ready to send live funds.

POST

Path variableValueDescription

weblinkFinal path segment from the payout URL in items[].cards[].cardCode.

Sample — send a request to see live data

{
  "transactionId": "fc894d78-e978-46c0-0748-08ded1b0af32",
  "payoutBatchId": "DZGTNDS9H3BWS",
  "isProcessing": true
}

Time: Not sentSize: —