Accept Multi-seller Payments

DOCSCURRENT

Last updated: May 13th, 10:51am

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

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

Create an order

To create an order for multi-merchant 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-merchant 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.

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

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-merchant 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"