marketplaces

Move Money

Important: PayPal for Marketplaces is a limited-release solution at this time. It is available to select partners for approved use cases. For more information, reach out to your PayPal account manager.

Marketplaces moves money from partner to merchant in three steps.

You'll use your REST API access token in these calls.

1. Create an order

The create order call to v1/checkout/orders/ creates an order with status as created. Save the associated order ID returned to pass to subsequent calls.

To create an order:

Include the Authorization, Accept, PayPal-Request-Id, and Content-Type headers in your request to POST v1/checkout/orders/. For more information about these headers, see REST API authentication and headers.

Set these parameters to define an order request:

Parameter Description
intent Set to SALE to capture the payment immediately after the buyer approves the payment.
application_context As a merchant, you can use this object to customize the PayPal payment flow experience.
redirect_urls Specify the return and cancel URLs:
  • return_url. The URL on your website to which to redirect a buyer when he or she approves a payment.
  • cancel_url. The URL on your website to which to redirect a buyer when he or she cancels a payment.
payment_method To choose the PayPal payment method, set to paypal.
purchase_units An array with details for the customer, merchant, partner, and order. The following values are optional:
  • reference_id The purchase unit within the context of the order.
  • description The purchase unit description.
  • invoice_number An external invoice number for this order. This value is returned in transaction and settlement reports.
  • partner_fee_details The partner fee that is collected for the original transaction. Contains the receiver and amount objects.
  • Important: Currency codes for partner_fee_details and the transaction amount must be the same.

Sample API request

Example create order request:

curl -v -X POST https://api.sandbox.paypal.com/v1/checkout/orders \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer Access-Token" \
  -H "PayPal-Partner-Attribution-Id: EXAMPLE_MP" \
  -d '{
  "purchase_units": [
  {
    "reference_id": "store_mobile_world_order_1234",
    "description": "Mobile World Store order-1234",
    "amount": {
      "currency": "USD",
      "details": {
        "subtotal": "1.09",
        "shipping": "0.02",
        "tax": "0.33"
      },
      "total": "1.44"
    },
    "payee": {
      "email": "seller@example.com"
    },
    "items": [
    {
      "name": "NeoPhone",
      "sku": "sku03",
      "price": "0.54",
      "currency": "USD",
      "quantity": "1"
    },
    {
      "name": "Fitness Watch",
      "sku": "sku04",
      "price": "0.55",
      "currency": "USD",
      "quantity": "1"
    }],
    "shipping_address": {
      "line1": "2211 N First Street",
      "line2": "Building 17",
      "city": "San Jose",
      "country_code": "US",
      "postal_code": "95131",
      "state": "CA",
      "phone": "(123) 456-7890"
    },
    "shipping_method": "United Postal Service",
    "partner_fee_details": {
      "receiver": {
        "email": "partner@example.com"
      },
      "amount": {
        "value": "0.01",
        "currency": "USD"
      }
    },
    "payment_linked_group": 1,
    "custom": "custom_value_2388",
    "invoice_number": "invoice_number_2388",
    "payment_descriptor": "Payment Mobile World"
  }],
  "redirect_urls": {
    "return_url": "https://example.com/return",
    "cancel_url": "https://example.com/cancel"
  }
}'

Sample API response

A successful create order request returns an HTTP 2nn status code. Any other status value indicates an error. In this case, correct the problem and resubmit the order.

Example response to the preceding order request:

{
  "id": "8RU61172JS455403V",
  "gross_total_amount": {
    "value": "1.44",
    "currency": "USD"
  },
  "purchase_units": [
  {
    "reference_id": "store_mobile_world_order_1234",
    "description": "Mobile World Store order-1234",
    "amount": {
      "currency": "USD",
      "details": {
        "subtotal": "1.09",
        "shipping": "0.02",
        "tax": "0.33"
      },
      "total": "1.44"
    },
    "payee": {
      "email": "seller@example.com"
    },
    "items": [
    {
      "name": "NeoPhone",
      "sku": "sku03",
      "price": "0.54",
      "currency": "USD",
      "quantity": "1"
    },
    {
      "name": "Fitness Watch",
      "sku": "sku04",
      "price": "0.55",
      "currency": "USD",
      "quantity": "1"
    }],
    "shipping_address": {
      "recipient_name": "John Doe",
      "default_address": false,
      "preferred_address": false,
      "primary_address": false,
      "disable_for_transaction": false,
      "line1": "2211 N First Street",
      "line2": "Building 17",
      "city": "San Jose",
      "country_code": "US",
      "postal_code": "95131",
      "state": "CA",
      "phone": "(123) 456-7890"
    },
    "shipping_method": "United Postal Service",
    "partner_fee_details": {
      "receiver": {
        "email": "partner@example.com"
      },
      "amount": {
        "value": "0.01",
        "currency": "USD"
      }
    },
    "payment_linked_group": 1,
    "custom": "custom_value_2388",
    "invoice_number": "invoice_number_2388",
    "payment_descriptor": "Payment Mobile World",
    "status": "CAPTURED"
  }],
  "redirect_urls": {
    "return_url": "https://example.com/return",
    "cancel_url": "https://example.com/cancel"
  },
  "create_time": "2017-04-26T21:18:49Z",
  "links": [
  {
    "href": "https://api.paypal.com/v1/checkout/orders/8RU61172JS455403V",
    "rel": "self",
    "method": "GET"
  },
  {
    "href": "https://www.paypal.com/webapps/hermes?token=8RU61172JS455403V",
    "rel": "approval_url",
    "method": "GET"
  },
  {
    "href": "https://api.paypal.com/v1/checkout/orders/8RU61172JS455403V",
    "rel": "cancel",
    "method": "DELETE"
  }],
  "status": "CREATED"
}

2. Pay an order

Your customers use a payment instrument to pay for an order.

In addition to the standard Accept, Content-Type, PayPal-Request-Id, and Authorization headers, include the PayPal-Client-Metadata-Id and PayPal-Partner-Attribution-Id headers.

In the URL, specify the ID that the create order call returns.

In the JSON request body, set the disbursement_mode parameter to DELAYED. PayPal holds the money until you call /v1/payments/referenced-payouts-items to disburse funds. For example, you can distribute funds automatically after an order ships.

Note: To learn more about delayed disbursement, see Managing risk for Connected or Managed integrations.

Sample API request

This sample request creates a delayed disbursement:

curl -v https://api.sandbox.paypal.com/v1/checkout/orders/875532314N6767612/pay \
  -X POST \
  -H "PayPal-Client-Metadata-Id: 1495725899514oren" \
  -H "PayPal-Request-Id: 9c5e3668-cb92-4a40-99b7-c74cb68913f4" \
  -H "PayPal-Partner-Attribution-Id: Example_Marketplace" \
  -H "Authorization: Bearer Access-Token" \
  -H "Content-Type: application/json" \
  -d ‘{
  "disbursement_mode": "DELAYED"
}’

Sample API response

The response from the previous request is:

{
  "order_id": "875532314N6767612",
  "status": "APPROVED",
  "payer_info": {
    "email": "test_payer@example.com",
    "first_name": "Jake",
    "last_name": "Doe",
    "payer_id": "9WVBNYPKKNBJS",
    "phone": "4087811648",
    "country_code": "US",
    "shipping_address": {
      "recipient_name": "John Doe",
      "default_address": false,
      "preferred_address": false,
      "primary_address": false,
      "disable_for_transaction": false,
      "line1": "2211 N First Street",
      "line2": "Building 17",
      "city": "San Jose",
      "country_code": "US",
      "postal_code": "95131",
      "state": "CA"
    }
  },
  "create_time": "2017-04-26T21:21:50Z",
  "update_time": "2017-04-26T21:21:50Z",
  "links": [
  {
    "href": "https://api.paypal.com/v1/checkout/orders/8RU61172JS455403V",
    "rel": "self",
    "method": "GET"
  }]
}

This call is asynchronous. Even if the response reports the APPROVED status, you must determine whether the transaction was approved. You do this in either of the show orders calls:

3. Disburse funds

PayPal disburses the funds to the partner and merchant.

Pass these parameters in the request body:

Parameter Description
reference_id The transaction ID for the payout. The pay for order call generates a webhook, which returns the transaction ID.
reference_type The reference type. Set to TRANSACTION_ID.

Sample API request

To make a payment disbursement:

curl -v https://api.sandbox.paypal.com/v1/payments/referenced-payouts-items \
  -X POST \
  -H "Content-Type: application/json" \
  -H "PayPal-Request-Id: postman-request-1480716758" \
  -H "Authorization: Bearer Access-Token" \
  -H "PayPal-Partner-Attribution-Id: Example_Marketplace" \
  -d '{
  "reference_id": "29N36144XH0198422",
  "reference_type": "TRANSACTION_ID"
}'

Sample API response

A successful request returns the HTTP 200 Success status code and includes the following response body:

{
  "item_id": "g8rfiM0u38L_FJ6qqA-3yHjaTFuTEjdK5ef2WbcpdDsQOci_Lk-we3dHjNNpEcY=",
  "processing_state": {
    "status": "SUCCESS"
  },
  "reference_id": "29N36144XH0198422",
  "reference_type": "TRANSACTION_ID",
  "payout_transaction_id": "67B93249N8969944D",
  "external_reference_id": "postman-request-1480713480",
  "payout_amount": {
    "currency_code": "USD",
    "value": "0.27"
  },
  "payout_destination": "B2A2BDS5DBA4Y",
  "links": [
  {
    "href": "https://api.sandbox.paypal.com/v1/payments/referenced-payouts-items/g8rfiM0u38L_FJ6qqA-3yHjaTFuTEjdK5ef2WbcpdDsQOci_Lk-we3dHjNNpEcY=",
    "rel": "self",
    "method": "GET",
    "encType": "application/json"
  }]
}

The response includes these fields:

Field Description
processing_state The status of the payout, which is SUCCESS in this case.
item_id A unique ID that PayPal creates for the payout request.
reference_id The transaction ID of the transaction to disburse to the merchant.
payout_transaction_id The encrypted PayPal ID for the payout.
payout_amount The exact amount and currency to be disbursed.
payout_destination The payer ID of the account that receives the funds.
links A HATEOAS link. Use to show details for the payout. For example:
GET "href": "https://api.sandbox.paypal.com/v1/payments/referenced-payouts-items/g8rfiM0u38L_FJ6qqA-3yHjaTFuTEjdK5ef2WbcpdDsQOci_Lk-we3dHjNNpEcY="

Note: PayPal deducts fees from the merchant’s funds.

Next

Feedback