PayPal Payouts

PayPal Payouts allow you to send money directly to a recipient's PayPal account via BR-DGE. This is useful for marketplace seller settlements, prize disbursements, refund credits, or any scenario where you need to push funds to a PayPal user.

📘
Prerequisite
Merchants must have Payouts enabled on their PayPal account before using this feature. Contact your PayPal account manager or PayPal support to enable it.

How It Works

PayPal Payouts via BR-DGE are asynchronous:

Step	Who	What Happens
1	Your server	Sends a payout request to BR-DGE
2	BR-DGE	Returns a synchronous `Pending` response
3	BR-DGE	Sends a notification with the final payout outcome

🚧
The Synchronous Response Is Always Pending
The immediate API response will always return a status of Pending. The actual success or failure of the payout is delivered asynchronously via a BR-DGE notification. Do not treat the Pending response as confirmation of a successful payout.

Send a Payout

POST to /v1/payouts with the payout amount, currency, and recipient details.

You must include at least one PayPal recipient identifier in the paymentInstrument object.

Recipient Identifiers

Field	Description
`paypalAccountId`	The recipient's PayPal account ID
`email`	The recipient's email address registered with PayPal
`phoneNumber`	The recipient's phone number registered with PayPal

Request

{
  "amount": 1000,
  "currencyCode": "GBP",
  "paymentInstrument": {
    "payPalAccountId": "DZDDTT5CW57HW",
    "type": "paypal"
  },
  "recipient": {
    "firstName": "Ray",
    "lastName": "Patyou",
    "customerId": "0a3a0f14-1225-466f-be8b-868285ac4ead",
    "email": "[email protected]",
    "dateOfBirth": "2002-02-20"
  },
  "reference": "12345"
}

Response

{
  "code": "2101",
  "id": "68ee1d8ae01ebf3dca2dd10d1203a482",
  "message": "Pending",
  "paymentId": "ffa330d8-6f85-44ed-acf2-07b314eda210",
  "psp": {
    "name": "PayPal-Direct",
    "transactionId": "Z8BYMZSLPTMX2"
  },
  "amount": 1000,
  "currencyCode": "GBP"
}

Store the paymentId — you'll need it to match up the final outcome when you receive the asynchronous notification from BR-DGE.

What Happens Next

Once BR-DGE has processed the payout with PayPal, you'll receive a notification with the final outcome. See the PayPal Notifications guide for details on notification structure and authentication.