Accept multi-merchant payments
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
tocapture
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, a504
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
anddata-merchant-id
in the SDK. - Use Postman to explore and test PayPal APIs.
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/orders2 -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 onepurchase_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
tocapture
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
anddata-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/capture2 -H "Content-Type: application/json"3 -H "Authorization: Bearer ACCESS-TOKEN"4 -d '{}'
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 apurchase_unit
can be inspected by looking at the status. For example,/purchase_units/@reference_id=='REFID-1'/payments/captures/status
isCOMPLETED
. - Each
purchase_unit
that is captured has a correspondingpayments.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"