Buvei
API ReferencePayouts

Create Payout

Initiate a PayPal payout. Requires X-Idempotency-Key.

POST/open-api/v1/payouts

Initiates a PayPal payout to the supplied payee. Funds are debited from your project wallet immediately. Final state (SUCCESS / FAILED) is delivered asynchronously via webhook.

Required header

X-Idempotency-Keystringheaderrequired

Unique key per logical request (e.g. your own order id). Retrying with the same key returns the same merOrderNo and does not double-charge. Distinct from X-Nonce (which is one-time anti-replay and must change on every retry).

Body

paymentTypestringbodyrequired

Currently only "PayPal".

arriveCurrencystringbodyrequired

ISO-3 code the payee receives. Must be one of the supported currencies: USD · GBP · EUR · AUD · JPY · CAD · MXN. Any other value returns 400 Unsupported currency: <code>.

arriveAmountintegerbodyrequired

Amount in minor units (cents) of arriveCurrency. Min 1.

payeeobjectbodyrequired

Payee details. Full payload required on every request — we do not persist a payee book.

remarkstringbody
Free-text up to 256 chars. Surfaces in payout history.

Response

merOrderNostring
Our order number. Use this for subsequent retrieve / cancel.
statusstring
PENDING, PROCESSING, UNCLAIMED, SUCCESS, FAILED, or CANCELED. Initial response is usually PENDING; terminal state comes via webhook.
paymentTypestring
arriveCurrencystring
arriveAmountinteger
Cents.
quoteRatenumber
settleAmountinteger
USD cents debited from wallet.
payeeFirstNamestring
payeeLastNamestring
payeeAccountNostring
remarkstring
createdAtinteger
Epoch ms.
completedAtinteger
Epoch ms, null until terminal.
canCancelboolean
true only if status is non-terminal AND created ≥ 24h ago.
Request
{
  "paymentType": "PayPal",
  "arriveCurrency": "EUR",
  "arriveAmount": 10000,
  "payee": {
    "firstName": "John",
    "lastName": "Smith",
    "accountNo": "[email protected]",
    "payeeType": "PERSON"
  },
  "remark": "Order 88231"
}
Response
{
  "code": 0,
  "message": "SUCCESS",
  "data": {
    "merOrderNo": "PO20260528155955tdi9fpi4",
    "status": "PENDING",
    "paymentType": "PayPal",
    "arriveCurrency": "EUR",
    "arriveAmount": 10000,
    "quoteRate": 0.8624,
    "settleAmount": 11696,
    "payeeFirstName": "John",
    "payeeLastName": "Smith",
    "payeeAccountNo": "[email protected]",
    "remark": "Order 88231",
    "createdAt": 1779955195000,
    "completedAt": null,
    "canCancel": false
  }
}

The wallet is debited synchronously. On terminal FAILED or CANCELED, the full amount is refunded automatically and a PAYOUT_FAILED / PAYOUT_CANCELED webhook is delivered.

On this page

Required header
Body
Response