marketplaces

Marketplaces Orders API Integration Guide

Orders API integration note:
  • PayPal for Marketplaces is available to select partners for approved use cases. It is aimed at marketplaces, crowdfunding, and multi-party commerce platforms.
  • You can also use the Orders API with Express Checkout to give your buyers a simplified checkout experience.

Overview

This guide shows you how to create, view, pay for orders, and disburse funds based on order approval. You can leverage these Orders API features:

Feature Use to
Partner fees Collect funds from any party.
Holds Place an automatic hold on all PayPal payments made on the platform.
Disbursements Control PayPal’s release of funds to your seller’s PayPal account (Connected path) or bank account (Managed path). Delayed disbursement does not release the funds until you trigger disbursement.
Multi-seller payment Process payments from multiple sellers at the same time. Your customers experience one streamlined checkout no matter how many sellers they buy from.
Notifications Receive real-time responses on the order status after you create or pay for an order. In addition, webhook notifications are sent to your application with the order status.
Loss account
(Managed path only)
Facilitate reverse movement of funds. You own loss liability with a Managed path integration. PayPal reverses these transactions from your loss account.
Payment instruments Pay for an order with a variety of payment instruments.
Channel billing agreements Enable your customers to save PayPal as a payment method on your marketplace.

Integration steps

Tip: Try the Order and Pay API demos:
  • To begin the demo, click PayPal Checkout.
  • At the end of the demo, view API history to see request and response information.

To use the Orders API to integrate payment processing:

1. Required Meet the prerequisites.
2. Required Create order.
3. Required Pay for order.
4. Optional Show order status.
5. Optional Refund payment.
6. Required Disburse funds.

Prerequisites

PayPal must approve partners and the partners must sign a contract before they can use the Orders API. PayPal uses a variety of criteria to evaluate and approve partners to handle orders.

Before you can use the Orders API, you must:

Set up and use webhooks

PayPal APIs use webhooks for event notification. A webhook is an HTTP callback that receives notification messages for events. For information, see set up webhooks.

Create order

To create an order:

POST https://api.sandbox.paypal.com/v1/checkout/orders

In addition to the standard Accept, Content-Type, PayPal-Request-Id, and Authorization headers, include the PayPal-Partner-Attribution-Id header with a unique build notation (BN) code. If you do not have a BN code, contact your PayPal account manager. For more information, see HTTP request headers.

To define an order, include the URLs to which to redirect the customer after he or she approves or cancels the order, the order details, and the payment fees. For details, see the Orders API reference.

To create an order:

curl https://api.sandbox.paypal.com/v1/checkout/orders \
    -X POST \
  -H "PayPal-Client-Metadata-Id: 1495722184170oren" \
  -H "PayPal-Request-Id: b992fcd6-41b6-43b5-b99a-be9acaf85727" \
  -H "PayPal-Partner-Attribution-Id: Example_Marketplace" \
  -H "Authorization: Bearer Access-Token" \
  -H "Content-Type: application/json" \
  -d '{
    "purchase_units": [{
        "reference_id": "pu1_forward fashions",
        "description": "pu1_description",
        "amount": {
            "currency": "USD",
            "details": {
                "subtotal": "100.00",
                "shipping": "0.00",
                "tax": "0.00"
            },
            "total": "100.00"
        },
        "payee": {
            "merchant_id": "8LQLM2ML4ZTYU"
        },
        "items": [{
            "name": "Denim Woven Shirt",
            "sku": "sku01",
            "price": "100.00",
            "currency": "USD",
            "quantity": 1,
            "supplementary_data": [],
            "postback_data": []
        }],
        "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": "john@example.com"
            },
            "amount": {
                "value": "16.80",
                "currency": "USD"
            }
        },
        "payment_linked_group": 1,
        "custom": "oren",
        "invoice_number": "invoice_oren_4262",
        "payment_descriptor": "Example_Marketplace"
    }],
    "metadata": {
        "supplementary_data": [],
        "postback_data": []
    },
    "redirect_urls": {
        "return_url": "https://example.com/return",
        "cancel_url": "https://example.com/cancel"
    }
}'

A successful request returns an HTTP 2XX status code. Any other status code indicates an error. Correct the problem and resubmit the order.

The response to the previous order request is:

Headers:
201 Created
PayPal-Debug-Id: e6692015bc1c0
Body:
{
    "id": "875532314N6767612",
    "gross_total_amount": {
        "value": "100.00",
        "currency": "USD"
    },
    ...
    "links": [{
            "href": "https://api.sandbox.paypal.com/v1/checkout/orders/875532314N6767612",
            "rel": "self",
            "method": "GET"
        },
        {
            "href": "https://www.sandbox.paypal.com/webapps/hermes?token=875532314N6767612",
            "rel": "approval_url",
            "method": "REDIRECT"
        },
        {
            "href": "https://api.sandbox.paypal.com/v1/checkout/orders/875532314N6767612",
            "rel": "cancel",
            "method": "DELETE"
        }
    ],
    "status": "CREATED"
}

The links array contains HATEOAS links that enable you to complete these actions for the order:

Action HATEOAS link
Show order details
{
    "href": "https://api.sandbox.paypal.com/v1/checkout/orders/875532314N6767612",
    "rel": "self",
    "method": "GET"
}
Redirect customer to URL to approve order
{
    "href": "https://www.sandbox.paypal.com/webapps/hermes?token=875532314N6767612",
    "rel": "approval_url",
    "method": "REDIRECT"
}
Delete the order
{
    "href": "https://api.sandbox.paypal.com/v1/checkout/orders/875532314N6767612",
    "rel": "cancel",
    "method": "DELETE"
}

Pay for 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.

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"
}’

The response from the previous request is:

Headers:
201 Created
Body:
{
    "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. To do so, call either:

Additional ways to pay

In addition to PayPal payments, the Orders API accepts a PayPal billing agreement ID, if your customer has set up an agreement.

To pay with a PayPal billing agreement:

curl -v https://api.sandbox.paypal.com/v1/checkout/orders/21E005655U660730L/pay \
  -X POST \
  -H "Authorization: Bearer Access-Token" \
  -H "Content-Type: application/json" \
  -d '{
    "disbursement_mode": "DELAYED",
    "payer": {
        "payment_method": "paypal",
        "funding_instruments": [{
            "billing": {
                "billing_agreement_id": "B-015762388"
            }
        }]
    }
}'

Show order status

For a transaction, the webhook notification contains a sale feature field that includes an ID and a link to show status details or refund the payment.

Action Link
Show status details
"href": "https://api.sandbox.paypal.com/v1/payments/capture/29N36144XH0198422",
"method": "GET"
Refund payment
"href": "https://api.sandbox.paypal.com/v1/payments/capture/29N36144XH0198422/refund",
"method": "POST"

Refund payment

You can refund a payment an order, by ID:

curl -v https://api.sandbox.paypal.com//v1/payments/capture/3CB62566PT644045J/refund \
  -X POST \
  -H "Authorization: Bearer Access-Token" \
  -H "Content-Type: application/json"

The capture_id is either:

Specify these parameters in the JSON request body:

Parameter Description
amount The currency and total amount to refund.
custom The transaction ID in the create a purchase unit for the order call.
invoice_number The seller-specific order ID in the create a purchase unit for the order call.

Pass the PayPal-Client-Metadata-Id and PayPal-Auth-Assertion request headers with the standard Accept, Content-Type, PayPal-Request-Id, and Authorization request headers.

For first-party calls, the value is:

base64-encoding-of-({"alg":"none"}).base64-encoding-of-({"iss":"<client_id","payer_id":"payer_id"})>.

Note: The previous example contains two period (.) characters, which are required. The payer_id is the seller's payer ID.

To generate the value for the PayPal-Auth-Assertion request header:

import org.apache.commons.codec.binary.Base64;
public class Base64Encode {
    public static void main(String[] args) {
        String header = "{\"alg\":\"none\"}";
        String payload = "{\"email\":\"identity_seller@paypal.com\",\"iss\":\"Acuy17p2LcOf9RMv8SUVBb3wic3FPEP2NHFFqfSCBRFrNFdmbC1JQ0w8HIKRxW3RDy2R8QTL93eptFYl\"}";
        //iss is the client id of the actor and email is the email id of the subject
        byte[] encodedBytes = Base64.encodeBase64(header.getBytes());
        System.out.println("Header encoded " + new String(encodedBytes));
        byte[] encodedBytesPayload = Base64.encodeBase64(payload.getBytes());
        System.out.println("Payload encoded " + new String(encodedBytesPayload));
        System.out.println("Paypal-Auth-Assertion=" + new String(encodedBytes) + "." + new String(encodedBytesPayload) + ".");
    }
}

Specify the tracking ID from the risk call, which enables PayPal to confirm that a valid device and application made the transaction.

To refund the payment for an order:

curl -v https://api.sandbox.paypal.com//v1/payments/capture/capture_id/refund \
  -X POST \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer Access-Token" \
  -d '{
    "amount": {
        "currency": "USD",
        "total": "0.70"
    },
    "custom": "custom_29N36144XH0198422",
    "invoice_number": "inv_29N36144XH0198422"
}'

The response includes:

  • A refund ID, 2M4379007H634953P.
  • A set of HATEOAS links to show details for the refund, parent payment, and original payout.

For example:

Headers:
200 OK
Body:
{
    "id": "2M4379007H634953P",
    "state": "completed",
    "amount": {
        "total": "0.70",
        "currency": "USD"
    },
    "refund_from_received_amount": {
        "value": "0.67",
        "currency": "USD"
    },
    "refund_from_transaction_fee": {
        "value": "0.03",
        "currency": "USD"
    },
    "total_refunded_amount": {
        "value": "0.70",
        "currency": "USD"
    },
    "parent_payment": "PAYID-LBA6I7Y200213815P317172G",
    "capture_id": "29N36144XH0198422",
    "create_time": "2017-12-02T14:21:51.051Z",
    "update_time": "2017-12-02T14:21:51.051Z",
    "links": [{
            "href": "https://api.sandbox.paypal.com/v1/payments/refund/2M4379007H634953P",
            "rel": "self",
            "method": "GET"
        },
        {
            "href": "https://api.sandbox.paypal.com/v1/payments/payment/PAYID-LBA6I7Y200213815P317172G",
            "rel": "parent_payment",
            "method": "GET"
        },
        {
            "href": "https://api.sandbox.paypal.com/v1/payments/capture/29N36144XH0198422",
            "rel": "capture",
            "method": "GET"
        }
    ]
}

Additional checkout experience options

Shortcut

Shortcut is an optimized checkout experience that enables you to skip collecting your customer's shipping address, email address, and telephone number on your checkout page — the information is pre-filled based on PayPal data.

Patch cart

With patch cart, your customers can change the shipping amount and shipping address on the PayPal checkout page. Call the PATCH operation and provide the purchase units that you want to update.

PATCH v1/checkout/orders/order_id

Disburse funds

Note: You must disburse funds only if you choose delayed disbursement.

PayPal disburses the funds to the partner and seller.

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.

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"
}'

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

Headers:
200 Success
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 seller.
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 seller’s funds.

Congratulations

You have set up orders.

Feedback

Have feedback?

Let us know.