# Accept multi-merchant payments (/limited-release/commerce-platform/accept-payments/standard/customize/accept-multi-merchant-payments) 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. ## Know before you code [#know-before-you-code] * Before implementing multi-merchant payments, complete [Seller Onboarding](/limited-release/commerce-platform/onboard-merchants/) to onboard merchants to your platform. * The instructions in [Get Started](/api/rest/authentication/) will help you get your access token. * This server-side integration uses the [Orders V2 REST API](/api/orders/v2), where each `purchase_unit` object represents a purchase from a single merchant. The information on this page does not pertain to Orders V1 REST API. * You must set `intent` to `capture` in the [create order](/api/orders/v2/orders-create) call for this feature to work. To learn more, see [Immediate Capture](/limited-release/commerce-platform/accept-payments/capture-instant-transfer/). * 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-merchant payments are not available with Venmo and Alternative Payment Methods. * All purchase units in a multi-merchant payment must use the same currency and the same shipping information. * Each purchase unit results in a separate transaction. * In multi-merchant payments, some purchase units may successfully process while others may fail to process. * For the order to capture, the merchant must be in good standing. For instance, the merchant account cannot be locked, closed, or restricted. The merchant 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 merchant in a multi-merchant 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](/limited-release/commerce-platform/accept-payments/standard/) 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. > **Info:** **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. ## 1. Create an order [#1-create-an-order] To create an order for multi-merchant payments, copy the following code and [modify](/limited-release/commerce-platform/v2/payment/multisellerpayment#modify-the-code) it: #### cURL ```bash lineNumbers curl -v -X POST https://api-m.sandbox.paypal.com/v2/checkout/orders \ -H 'Content-Type: application/json' \ -H 'Authorization: Bearer ACCESS-TOKEN' \ -H 'PayPal-Partner-Attribution-Id: BN-CODE' \ -d '{ "intent": "CAPTURE", "purchase_units": [ { "reference_id": "REFID-1", "payee": { "email_address": "merchant@example.com", "merchant_id": "WNM9VDLXSZPFW" }, "amount": { "currency_code": "USD", "value": "100.00" }, "payment_instruction": { "disbursement_mode": "INSTANT", "platform_fees": [ { "amount": { "currency_code": "USD", "value": "2.00" } } ] } }, { "reference_id": "REFID-2", "payee": { "email_address": "merchant2@example.com", "merchant_id": "WNM9VDABCD1" }, "amount": { "currency_code": "USD", "value": "50.00" }, "payment_instruction": { "disbursement_mode": "INSTANT", "platform_fees": [ { "amount": { "currency_code": "USD", "value": "2.00" } } ] } } ] }' ``` #### Node ```javascript lineNumbers var express = require('express'); var request = require('request'); express().post('/my-server/create-order', function(req, res) { request.post( "https://api-m.sandbox.paypal.com/v2/checkout/orders", { headers: { "Content-Type": application/json", "Authorization": "Bearer ACCESS-TOKEN", "PayPal-Partner-Attribution-Id": "BN-CODE", }, body: { intent: "CAPTURE", purchase_units: [ { amount: { currency_code: "USD", value: "100.00", }, payee: { email_address: "merchant@example.com", merchant_id: "WNM9VDLXSZPFW" }, payment_instruction: { disbursement_mode: "INSTANT", platform_fees: [ { amount: { currency_code: "USD", value: "25.00", }, }, ], }, }, ], }, json: true, }, function (err, response, body) { if (err) { console.error(err); return res.sendStatus(500); } res.json({ id: body.id, }); } )} ); ``` ### Modify the code [#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](/api/rest/requests/#paypal-partner-attribution-id) to receive revenue attribution. To find your BN code, see [Code and Credential Reference](/platforms/create-account/#link-bncode). * 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 [#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. ## 2. Capture an order [#2-capture-an-order] After your buyer approves the order, call [capture order](/api/orders/v2/orders-capture) 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](/limited-release/commerce-platform/v2/payment/multisellerpayment#status-codes) for more details. Copy the following code and modify it: #### cURL ```bash lineNumbers curl -v -X POST https://api-m.paypal.com/v2/checkout/orders/5O190127TN364715T/capture \ -H 'Content-Type: application/json' \ -H 'Authorization: Bearer ACCESS-TOKEN' \ -H 'PayPal-Partner-Attribution-Id: BN-CODE' \ -d '{}' ``` #### Node ```javascript lineNumbers var express = require('express'); var request = require('request'); express().post('/my-server/handle-approve/:id', function(req, res) { request.post( "https://api-m.sandbox.paypal.com/v2/checkout/orders/" + req.params.id + "/capture", { headers: { "Content-Type": "application/json", "Authorization": "Bearer ACCESS-TOKEN", "PayPal-Partner-Attribution-Id": "BN-CODE" } }, function (err, response, body) { if (err) { console.error(err); return res.sendStatus(500); } res.json({ status: "success", }); } )} ); ``` > **Info:** **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](/limited-release/commerce-platform/accept-payments/standard/) flow. ### Modify the code [#modify-the-code-1] * Change `ACCESS-TOKEN` to your access token. * Change `BN-CODE` to your [PayPal attribution ID](/api/rest/requests/#paypal-partner-attribution-id) to receive revenue attribution.To find your BN code, see [Code and Credential Reference.](/platforms/create-account/#link-bncode) ### Step result [#step-result-1] 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. ```json lineNumbers { "id":"5O190127TN364715T", "status":"COMPLETED", "intent":"CAPTURE", "payer":{ "name":{ "given_name":"John", "surname":"Doe" }, "email_address":"customer@example.com", "payer_id":"QYR5Z8XDVJNXQ" }, "purchase_units":[ { "reference_id":"REFID-1", "amount":{ "currency_code":"USD", "value":"75.00" }, "payee": { "email_address": "merchant@example.com", "merchant_id": "WNM9VDLXSZPFW" }, "shipping":{ "name":{ "full_name":"John Doe" }, "address":{ "address_line_1":"2211 N First Street", "address_line_2":"Building 17", "admin_area_2":"San Jose", "admin_area_1":"CA", "postal_code":"95131", "country_code":"US" } }, "payments":{ "captures":[ { "id":"3C679366HH908993G2", "status":"COMPLETED", "amount":{ "currency_code":"USD", "value":"75.00" }, "seller_protection":{ "status":"ELIGIBLE", "dispute_categories":[ "ITEM_NOT_RECEIVED", "UNAUTHORIZED_TRANSACTION" ] }, "final_capture":true, "disbursement_mode":"INSTANT", "seller_receivable_breakdown":{ "gross_amount":{ "currency_code":"USD", "value":"75.00" }, "paypal_fee":{ "currency_code":"USD", "value":"2.00" }, "net_amount":{ "currency_code":"USD", "value":"73.00" } }, "create_time":"2018-04-01T21:20:49Z", "update_time":"2018-04-01T21:20:49Z", "links":[ { "href":"https://api-m.paypal.com/v2/payments/captures/3C679366HH908993F", "rel":"self", "method":"GET" }, { "href":"https://api-m.paypal.com/v2/payments/captures/3C679366HH908993F/refund", "rel":"refund", "method":"POST" } ] } ] } }, { "reference_id":"REFID-2", "shipping":{ "name":{ "full_name":"John Doe" }, "address":{ "address_line_1":"2211 N First Street", "address_line_2":"Building 17", "admin_area_2":"San Jose", "admin_area_1":"CA", "postal_code":"95131", "country_code":"US" } }, "payments":{ "captures":[ { "id":"3C679366HH908993F1", "status":"COMPLETED", "amount":{ "currency_code":"USD", "value":"50.00" }, "seller_protection":{ "status":"ELIGIBLE", "dispute_categories":[ "ITEM_NOT_RECEIVED", "UNAUTHORIZED_TRANSACTION" ] }, "final_capture":true, "disbursement_mode":"INSTANT", "seller_receivable_breakdown":{ "gross_amount":{ "currency_code":"USD", "value":"50.00" }, "paypal_fee":{ "currency_code":"USD", "value":"2.00" }, "net_amount":{ "currency_code":"USD", "value":"48.00" } }, "create_time":"2018-04-01T21:20:49Z", "update_time":"2018-04-01T21:20:49Z", "links":[ { "href":"https://api-m.paypal.com/v2/payments/captures/3C679366HH908993F", "rel":"self", "method":"GET" }, { "href":"https://api-m.paypal.com/v2/payments/captures/3C679366HH908993F/refund", "rel":"refund", "method":"POST" } ] } ] } } ], "create_time":"2018-04-01T21:18:49Z", "update_time":"2018-04-01T21:20:49Z", "links":[ { "href":"https://api-m.paypal.com/v2/checkout/orders/5O190127TN364715T", "rel":"self", "method":"GET" } ] } ``` ## Status codes [#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 [#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 ```json lineNumbers { "id":"5O190127TN364715T", "status":"PARTIALLY_COMPLETED", "intent":"CAPTURE", "payer":{ "name":{ "given_name":"John", "surname":"Doe" }, "email_address":"customer@example.com", "payer_id":"QYR5Z8XDVJNXQ" }, "purchase_units":[ { "reference_id":"REFID-1", "amount":{ "currency_code":"USD", "value":"100.00" }, "payee": { "email_address": "merchant@example.com", "merchant_id": "WNM9VDLXSZPFW" }, "shipping":{ "name":{ "full_name":"John Doe" }, "address":{ "address_line_1":"2211 N First Street", "address_line_2":"Building 17", "admin_area_2":"San Jose", "admin_area_1":"CA", "postal_code":"95131", "country_code":"US" } }, "payments":{ "captures":[ { "status":"DECLINED", "error":{ "name":"UNPROCESSABLE_ENTITY", "details":[ { "issue":"TRANSACTION_REFUSED", "description":"The request was refused" } ], "message":"The requested action could not be performed, semantically incorrect, or failed business validation.", "debug_id":"2bbee1787c063", "links":[ { "href":"https://developer.paypal.com/api/orders/v2/error-messages", "rel":"information_link", "method":"GET" } ] } } ] } }, { "reference_id":"REFID-2", "shipping":{ "name":{ "full_name":"John Doe" }, "address":{ "address_line_1":"2211 N First Street", "address_line_2":"Building 17", "admin_area_2":"San Jose", "admin_area_1":"CA", "postal_code":"95131", "country_code":"US" } }, "payments":{ "captures":[ { "id":"3C679366HH908993F1", "status":"COMPLETED", "amount":{ "currency_code":"USD", "value":"50.00" }, "seller_protection":{ "status":"ELIGIBLE", "dispute_categories":[ "ITEM_NOT_RECEIVED", "UNAUTHORIZED_TRANSACTION" ] }, "final_capture":true, "disbursement_mode":"INSTANT", "seller_receivable_breakdown":{ "gross_amount":{ "currency_code":"USD", "value":"50.00" }, "paypal_fee":{ "currency_code":"USD", "value":"2.00" }, "net_amount":{ "currency_code":"USD", "value":"48.00" } }, "create_time":"2018-04-01T21:20:49Z", "update_time":"2018-04-01T21:20:49Z", "links":[ { "href":"https://api-m.paypal.com/v2/payments/captures/3C679366HH908993F", "rel":"self", "method":"GET" }, { "href":"https://api-m.paypal.com/v2/payments/captures/3C679366HH908993F/refund", "rel":"refund", "method":"POST" } ] } ] } } ], "create_time":"2018-04-01T21:18:49Z", "update_time":"2018-04-01T21:20:49Z", "links":[ { "href":"https://api-m.paypal.com/v2/checkout/orders/5O190127TN364715T", "rel":"self", "method":"GET" } ] } ``` ### HTTP 422 Unprocessable entity [#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. ```json lineNumbers { "name":"UNPROCESSABLE_ENTITY", "details":[ { "field":"/purchase_units/@reference_id=='REFID-1'", "issue":"INSTRUMENT_DECLINED", "description":"The instrument presented was either declined by the processor or bank, or it can't be used for this payment." }, { "field":"/purchase_units/@reference_id=='REFID-2'", "issue":"INSTRUMENT_DECLINED", "description":"The instrument presented was either declined by the processor or bank, or it can't be used for this payment." } ], "message":"The requested action could not be performed, semantically incorrect, or failed business validation.", "debug_id":"dd5464bfc40a0", "links":[ { "href":"https://developer.paypal.com/api/orders/v2/error-messages", "rel":"information_link", "method":"GET" }, { "href":"https://developer.paypal.com/api/orders/v2/error-messages", "rel":"information_link", "method":"GET" } ] ``` ### HTTP 504 Gateway Timeout [#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: ```bash lineNumbers curl -v -X GET https://api-m.sandbox.paypal.com/v2/checkout/orders/5O190127TN364715T \ -H 'Content-Type: application/json' \ -H 'Authorization: Bearer ACCESS-TOKEN' \ -H 'PayPal-Partner-Attribution-Id: BN-CODE' \ -H 'PayPal-Auth-Assertion: AUTH-ASSERTION-JWT' ```