Accept multi-merchant payments

DocsCurrent

Last updated: Oct 30th, 7:08am

Use multi-seller payments so that a buyer can check out from multiple sellers on your platform in one purchase. For example, a travel marketplace can host multiple sellers such as hotels, rental car companies, and entertainment sites, and the buyers can check out once from that marketplace with items from multiple sellers.

Know before you code

Before implementing multi-seller payments, complete Seller Onboarding to onboard sellers to your platform.

The instructions in Get Started will help you get your access token.

This server-side integration uses the Orders V2 REST API, where each purchase_unit object represents a purchase from a single seller. The information on this page does not pertain to Orders V1 REST API.

You must set intent to capture in the create order call for this feature to work. To learn more, see Immediate Capture.

This feature supports a maximum of 10 purchase_unit objects. There is a timeout limit of 20 seconds for the API response. If the 10 purchase units do not all process within that 20 seconds, a 504 timeout response is returned.

Multi-seller payments are not available with Venmo and Alternative Payment Methods.

All purchase units in a multi-seller payment must use the same currency and the same shipping information.

Each purchase unit results in a separate transaction.

In multi-seller payments, some purchase units may successfully process while others may fail to process.

For the order to capture, the seller must be in good standing. For instance, the seller account cannot be locked, closed, or restricted. The seller account must also be eligible if the payment source chosen by the buyer requires vetting, and the buyer must have provided consent to the API caller to transact on their behalf. If one seller in a multi-seller payment is not in good standing, the entire capture of the order will fail.

You can use this feature with payment buttons. See Set up payments for more information. If you use this feature with the JavaScript SDK, you must pass merchant-id and data-merchant-id in the SDK.

Use Postman to explore and test PayPal APIs.

Note: A single purchase will result in a separate transaction settled to each of the sellers and the buyer will see separate transactions on the payment method they used.

Create an order

To create an order for multi-seller payments, copy the following code and modify it:

cURL
Node

1curl -v -X POST https://api-m.sandbox.paypal.com/v2/checkout/orders
2  -H "Content-Type: application/json"
3  -H "Authorization: Bearer ACCESS-TOKEN"
4  -d '{
5    "intent": "CAPTURE",
6    "purchase_units": [
7      {
8         "reference_id": "REFID-1",
9         "payee": {
10               "email_address": "merchant@example.com"
11         },
12         "amount": {
13               "currency_code": "USD",
14               "value": "100.00"
15         },
16         "payment_instruction": {
17            "disbursement_mode": "INSTANT",
18            "platform_fees": [
19               {
20                  "amount": {
21                     "currency_code": "USD",
22                     "value": "2.00"
23                  }
24               }
25            ]
26         }
27      },
28      {
29         "reference_id": "REFID-2",
30         "payee": {
31            "email_address": "merchant2@example.com"
32         },
33         "amount": {
34            "currency_code": "USD",
35            "value": "50.00"
36         },
37         "payment_instruction": {
38            "disbursement_mode": "INSTANT",
39            "platform_fees": [
40               {
41                  "amount": {
42                        "currency_code": "USD",
43                        "value": "2.00"
44                  }
45               }
46            ]
47         }
48      }
49   ]
50}'

Modify the code

After you copy the code in the sample request, modify the following:

Change ACCESS-TOKEN to your access token.

Change BN-CODE to your PayPal attribution ID to receive revenue attribution.To find your BN code, see Code and Credential Reference.

The reference_id is required if you have more than one purchase_unit object.

Change the purchase_unit/payee object to specify the end receiver of the funds. If you do not specify a payee, PayPal assumes it is the API caller's account.

You must set intent to capture for this feature to work.

Optional: Change the purchase_unit/payment_instruction/platform_fees array to specify fees for the order.

Step result

A successful request results in the following:

Returns a HATEOAS link that redirects the buyer to a rel:approve URL where they can approve the order.

If a buyer is paying using PayPal, redirect the buyer to the approve link. After approval, you can capture the order.

If you are using the JavaScript SDK, you must pass merchant-id and data-merchant-id in the SDK to use multi-seller payments.

Capture an order

After your buyer approves the order, call capture order to capture the buyer's funds. During this call, PayPal attempts to capture all funds. If there are not sufficient funds to capture the total purchase, PayPal will capture as much as possible. See Status Codes for more details. Copy the following code and modify it:

cURL
Node

1curl -v -X POST https://api-m.paypal.com/v2/checkout/orders/5O190127TN364715T/capture
2  -H "Content-Type: application/json"
3  -H "Authorization: Bearer ACCESS-TOKEN"
4  -d '{}'

Note: Orders cannot be captured until the status of the order is set to APPROVED. The order status is set to APPROVED when the buyer successfully completes the checkout flow.

Modify the code

Change ACCESS-TOKEN to your access token.

Step result

A successful result returns the following:

A HTTP 201 CREATED if every purchase_unit has been captured. The status of a purchase_unit can be inspected by looking at the status. For example, /purchase_units/@reference_id=='REFID-1'/payments/captures/status is COMPLETED.

Each purchase_unit that is captured has a corresponding payments.capture object which includes details of the capture.

1{
2   "id":"5O190127TN364715T",
3   "status":"COMPLETED",
4   "intent":"CAPTURE",
5   "payer":{
6      "name":{
7         "given_name":"John",
8         "surname":"Doe"
9      },
10      "email_address":"customer@example.com",
11      "payer_id":"QYR5Z8XDVJNXQ"
12   },
13   "purchase_units":[
14      {
15         "reference_id":"REFID-1",
16         "amount":{
17            "currency_code":"USD",
18            "value":"75.00"
19         },
20         "payee": {
21                "email_address": "merchant@example.com",
22                "merchant_id": "WNM9VDLXSZPFW"
23         },
24         "shipping":{
25            "name":{
26               "full_name":"John Doe"
27            },
28            "address":{
29               "address_line_1":"2211 N First Street",
30               "address_line_2":"Building 17",
31               "admin_area_2":"San Jose",
32               "admin_area_1":"CA",
33               "postal_code":"95131",
34               "country_code":"US"
35            }
36         },
37         "payments":{
38            "captures":[
39               {
40                  "id":"3C679366HH908993G2",
41                  "status":"COMPLETED",
42                  "amount":{
43                     "currency_code":"USD",
44                     "value":"75.00"
45                  },
46                  "seller_protection":{
47                     "status":"ELIGIBLE",
48                     "dispute_categories":[
49                        "ITEM_NOT_RECEIVED",
50                        "UNAUTHORIZED_TRANSACTION"
51                     ]
52                  },
53                  "final_capture":true,
54                  "disbursement_mode":"INSTANT",
55                  "seller_receivable_breakdown":{
56                     "gross_amount":{
57                        "currency_code":"USD",
58                        "value":"75.00"
59                     },
60                     "paypal_fee":{
61                        "currency_code":"USD",
62                        "value":"2.00"
63                     },
64                     "net_amount":{
65                        "currency_code":"USD",
66                        "value":"73.00"
67                     }
68                  },
69                  "create_time":"2018-04-01T21:20:49Z",
70                  "update_time":"2018-04-01T21:20:49Z",
71                  "links":[
72                     {
73                        "href":"https://api-m.paypal.com/v2/payments/captures/3C679366HH908993F",
74                        "rel":"self",
75                        "method":"GET"
76                     },
77                     {
78                        "href":"https://api-m.paypal.com/v2/payments/captures/3C679366HH908993F/refund",
79                        "rel":"refund",
80                        "method":"POST"
81                     }
82                  ]
83               }
84            ]
85         }
86      },
87      {
88         "reference_id":"REFID-2",
89         "shipping":{
90            "name":{
91               "full_name":"John Doe"
92            },
93            "address":{
94               "address_line_1":"2211 N First Street",
95               "address_line_2":"Building 17",
96               "admin_area_2":"San Jose",
97               "admin_area_1":"CA",
98               "postal_code":"95131",
99               "country_code":"US"
100            }
101         },
102         "payments":{
103            "captures":[
104               {
105                  "id":"3C679366HH908993F1",
106                  "status":"COMPLETED",
107                  "amount":{
108                     "currency_code":"USD",
109                     "value":"50.00"
110                  },
111                  "seller_protection":{
112                     "status":"ELIGIBLE",
113                     "dispute_categories":[
114                        "ITEM_NOT_RECEIVED",
115                        "UNAUTHORIZED_TRANSACTION"
116                     ]
117                  },
118                  "final_capture":true,
119                  "disbursement_mode":"INSTANT",
120                  "seller_receivable_breakdown":{
121                     "gross_amount":{
122                        "currency_code":"USD",
123                        "value":"50.00"
124                     },
125                     "paypal_fee":{
126                        "currency_code":"USD",
127                        "value":"2.00"
128                     },
129                     "net_amount":{
130                        "currency_code":"USD",
131                        "value":"48.00"
132                     }
133                  },
134                  "create_time":"2018-04-01T21:20:49Z",
135                  "update_time":"2018-04-01T21:20:49Z",
136                  "links":[
137                     {
138                        "href":"https://api-m.paypal.com/v2/payments/captures/3C679366HH908993F",
139                        "rel":"self",
140                        "method":"GET"
141                     },
142                     {
143                        "href":"https://api-m.paypal.com/v2/payments/captures/3C679366HH908993F/refund",
144                        "rel":"refund",
145                        "method":"POST"
146                     }
147                  ]
148               }
149            ]
150         }
151      }
152   ],
153   "create_time":"2018-04-01T21:18:49Z",
154   "update_time":"2018-04-01T21:20:49Z",
155   "links":[
156      {
157         "href":"https://api-m.paypal.com/v2/checkout/orders/5O190127TN364715T",
158         "rel":"self",
159         "method":"GET"
160      }
161   ]
162}

Status codes

During capture, PayPal attempts to capture every purchase_unit. If there are not sufficient funds to capture all of them, PayPal captures as many units as funds are available for. In these cases, you receive one of the following status codes:

HTTP 207 Multi-Status: This status indicates that not every purchase_unit was captured.

HTTP 422 Unprocessable entity: This status indicates that no purchase_unit was captured.

There is also a timeout limit of 20 seconds for the API response. If the purchase_unit objects do not all process within that 20 seconds, an HTTP 504 Gateway Timeout response is returned.

HTTP 207 Multi-Status

If only some of the purchase_unit objects are captured, the status of the order is PARTIALLY_COMPLETED. You can get the status of each purchase_unit.

/purchase_units/@reference_id=='REFID-1'/payments/captures/status = DECLINED

/purchase_units/@reference_id=='REFID-2'/payments/captures/status = COMPLETED

1{
2   "id":"5O190127TN364715T",
3   "status":"PARTIALLY_COMPLETED",
4   "intent":"CAPTURE",
5   "payer":{
6      "name":{
7         "given_name":"John",
8         "surname":"Doe"
9      },
10      "email_address":"customer@example.com",
11      "payer_id":"QYR5Z8XDVJNXQ"
12   },
13   "purchase_units":[
14      {
15         "reference_id":"REFID-1",
16         "amount":{
17            "currency_code":"USD",
18            "value":"100.00"
19         },
20         "payee": {
21                "email_address": "merchant@example.com",
22                "merchant_id": "WNM9VDLXSZPFW"
23         },
24         "shipping":{
25            "name":{
26               "full_name":"John Doe"
27            },
28            "address":{
29               "address_line_1":"2211 N First Street",
30               "address_line_2":"Building 17",
31               "admin_area_2":"San Jose",
32               "admin_area_1":"CA",
33               "postal_code":"95131",
34               "country_code":"US"
35            }
36         },
37         "payments":{
38            "captures":[
39               {
40                  "status":"DECLINED",
41                  "error":{
42                     "name":"UNPROCESSABLE_ENTITY",
43                     "details":[
44                        {
45                           "issue":"TRANSACTION_REFUSED",
46                           "description":"The request was refused"
47                        }
48                     ],
49                     "message":"The requested action could not be performed, semantically incorrect, or failed business validation.",
50                     "debug_id":"2bbee1787c063",
51                     "links":[
52                        {
53                           "href":"https://developer.paypal.com/docs/api/orders/v2/#error-TRANSACTION_REFUSED",
54                           "rel":"information_link",
55                           "method":"GET"
56                        }
57                     ]
58                  }
59               }
60            ]
61         }
62      },
63      {
64         "reference_id":"REFID-2",
65         "shipping":{
66            "name":{
67               "full_name":"John Doe"
68            },
69            "address":{
70               "address_line_1":"2211 N First Street",
71               "address_line_2":"Building 17",
72               "admin_area_2":"San Jose",
73               "admin_area_1":"CA",
74               "postal_code":"95131",
75               "country_code":"US"
76            }
77         },
78         "payments":{
79            "captures":[
80               {
81                  "id":"3C679366HH908993F1",
82                  "status":"COMPLETED",
83                  "amount":{
84                     "currency_code":"USD",
85                     "value":"50.00"
86                  },
87                  "seller_protection":{
88                     "status":"ELIGIBLE",
89                     "dispute_categories":[
90                        "ITEM_NOT_RECEIVED",
91                        "UNAUTHORIZED_TRANSACTION"
92                     ]
93                  },
94                  "final_capture":true,
95                  "disbursement_mode":"INSTANT",
96                  "seller_receivable_breakdown":{
97                     "gross_amount":{
98                        "currency_code":"USD",
99                        "value":"50.00"
100                     },
101                     "paypal_fee":{
102                        "currency_code":"USD",
103                        "value":"2.00"
104                     },
105                     "net_amount":{
106                        "currency_code":"USD",
107                        "value":"48.00"
108                     }
109                  },
110                  "create_time":"2018-04-01T21:20:49Z",
111                  "update_time":"2018-04-01T21:20:49Z",
112                  "links":[
113                     {
114                        "href":"https://api-m.paypal.com/v2/payments/captures/3C679366HH908993F",
115                        "rel":"self",
116                        "method":"GET"
117                     },
118                     {
119                        "href":"https://api-m.paypal.com/v2/payments/captures/3C679366HH908993F/refund",
120                        "rel":"refund",
121                        "method":"POST"
122                     }
123                  ]
124               }
125            ]
126         }
127      }
128   ],
129   "create_time":"2018-04-01T21:18:49Z",
130   "update_time":"2018-04-01T21:20:49Z",
131   "links":[
132      {
133         "href":"https://api-m.paypal.com/v2/checkout/orders/5O190127TN364715T",
134         "rel":"self",
135         "method":"GET"
136      }
137   ]
138}

HTTP 422 Unprocessable entity

If none of the purchase_unit objects are successful, you get an HTTP 422 UNPROCESSABLE_ENTITY status returned with an array of errors that includes descriptions of why each purchase_unit was not captured.

1{
2   "name":"UNPROCESSABLE_ENTITY",
3   "details":[
4      {
5         "field":"/purchase_units/@reference_id=='REFID-1'",
6         "issue":"INSTRUMENT_DECLINED",
7         "description":"The instrument presented was either declined by the processor or bank, or it can't be used for this payment."
8      },
9      {
10         "field":"/purchase_units/@reference_id=='REFID-2'",
11         "issue":"INSTRUMENT_DECLINED",
12         "description":"The instrument presented was either declined by the processor or bank, or it can't be used for this payment."
13      }
14   ],
15   "message":"The requested action could not be performed, semantically incorrect, or failed business validation.",
16   "debug_id":"dd5464bfc40a0",
17   "links":[
18      {
19         "href":"https://developer.paypal.com/docs/api/orders/v2/#error-INSTRUMENT_DECLINED",
20         "rel":"information_link",
21         "method":"GET"
22      },
23      {
24         "href":"https://developer.paypal.com/docs/api/orders/v2/#error-INSTRUMENT_DECLINED",
25         "rel":"information_link",
26         "method":"GET"
27      }
28   ]

HTTP 504 Gateway Timeout

A multi-seller payment order can contain a maximum of 10 purchase_unit objects. There is a timeout limit of 20 seconds for the API response. If the 10 units do not all process within that 20 seconds, an HTTP 504 timeout response is returned. You can use the following GET request to get the latest order status:

1curl -v -X GET https://api-m.sandbox.paypal.com/v2/checkout/orders/5O190127TN364715T -H "Content-Type: application/json" -H "Authorization: Bearer ACCESS-TOKEN"