Orders 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, and pay for orders and disburse funds based on order approval. You can customize your integration by leveraging the following Orders API features:

  • 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 merchant’s PayPal account (Connected path) or bank account (Managed path). With instant disbursement, merchants receive funds as soon as a sale is complete. With delayed disbursement, funds aren't released until you trigger disbursement.

  • Multi-seller payment. Process payments from multiple merchants at once. Your customers experience one streamlined checkout regardless of how many merchants they’re purchasing from.

  • Notifications. Once an order is created or paid for, you receive real-time responses on the order status. In addition, notifications (webhooks) are sent to your application with the order status.

  • Loss account (Managed path only). Because you own loss liability with a Managed path integration, a loss account is configured to facilitate reverse movement of funds. 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.

Prerequisites

Partners must be approved and sign a contract before they can begin using the Orders API. PayPal evaluates partners on a variety of criteria before approving them to handle orders.

Before you can use the Orders API, you must:

Integration steps

To integrate payment processing through the Orders API:

Tip: Try the Order and Pay API demos.
  • Click the PayPal Checkout button to begin the demo.
  • At the end of the demo, view API history to see request and response information
1. Required Add a PayPal button.
2. Required Create order.
3. Required Pay for order.
4. Optional Show order status.
5. Optional Refund payment.
6. Required Disburse funds.

Add PayPal button

Follow the steps to add a PayPal button to your website.

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 these headers:

  • PayPal-Partner-Attribution-Id. Specify a unique build notation (BN) code. If you do not have a BN code, contact your PayPal account manager.

For more information about these headers, 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.

Sample API request

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,
            "category": "PHYSICAL",
            "supplementary_data": [],
            "postback_data": [],
            "item_option_selections": []
        }],
        "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://sandbox.paypal.com/checkout?mode=commit&rmi=1495725899514oren&useBraintree=false&disbursementMode=DELAYED",
        "cancel_url": "https://sandbox.paypal.com/checkout?mode=foo&rmi=1495725899514oren&useBraintree=false&disbursementMode=DELAYED"
    }
}'

Sample API response

  • To create an order, call /checkout/orders/. Save the associated order ID to pass to subsequent calls.

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

The response to the preceding 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 other actions for the order:

  • Show order details:

    (GET) "href": https://api.sandbox.paypal.com/v1/checkout/orders/6GJ5755276400205X
    
  • Redirect the customer to the URL to approve the order:

    (REDIRECT) "href": https://api.sandbox.paypal.com/webapps/hermes?token=6GJ5755276400205X
    
  • Delete the order:

    (DELETE) "href": https://api.sandbox.paypal.com/v1/checkout/orders/6GJ5755276400205X
    

Pay for order

Your customers can pay for an order with a variety of payment instruments.

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, pass the parameter order_id. Specify the ID returned from the create order call.

In the request body, pass the disbursement_mode parameter. Specify one of these disbursement modes:

  • DELAYED. PayPal holds the money until you call /v1/payments/referenced-payouts-items to disburse funds. For example, you could code logic to distribute funds automatically after a set period of time, when the order is processed for shipping, and so on.
  • INSTANT. PayPal disburses funds immediately when an order is complete. In this case, you do not need to call /v1/payments/referenced-payouts-items.

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

API request

To create a request for 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"
}’

API response

The response from the previous request:

Headers:
201 Created
Body:
{
  "order_id": "875532314N6767612",
  "status": "APPROVED",
  "payer_info": {
    ...
  }
},
"purchase_units": [],
"links": [{
  "href": "https://api.sandbox.paypal.com/v1/checkout/orders/875532314N6767612",
  "rel": "self",
  "method": "GET"
}],
}

The response for a call that sets disbursement to INSTANT is similar.

Additional ways to pay

In addition to PayPal payments, the Orders API accepts the following payment instruments:

  • PayPal billing agreement ID (if your customer has one set up).

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": "INSTANT",
    "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.

  • Show status details:

    "href": "https://api.sandbox.paypal.com/v1/payments/capture/29N36144XH0198422",
    "method": "GET"
    
  • Refund the payment:

    "href": "https://api.sandbox.paypal.com/v1/payments/capture/29N36144XH0198422/refund",
    "method": "POST"
    

Refund payment

To request payment refunds for an order, pass the capture ID in the URI:

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:

In the request body, specify:

  • amount. Currency and total amount to refund.

  • custom. The transaction ID that you specified when you created a purchase unit for the order.

  • invoice_number. The merchant-specific order ID that you specified when you created a purchase unit for the order.

Along with the standard headers (Accept, Content-Type, PayPal-Request-Id, and Authorization), pass PayPal-Client-Metadata-Id and PayPal-Auth-Assertion. For first-party calls, the value is:

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

Note: There are two period characters(.) in the example above which are required, and payer_id is the merchant's payer ID.

To use the PayPal-Auth-Assertion:

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 that you passed to the risk call, which enables PayPal to confirm that a valid device and application originated 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:

  • An ID for the refund (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 stored 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 chose delayed disbursement.

Funds are disbursed to the partner and the merchant.

In addition to the standard Accept, Content-Type, PayPal-Request-Id, and Authorization headers, include the respond-sync header.

  • To process the request asynchronously, specify respond-async. The POST response contains a link to the resource that you can use later to query the referenced payout status.

  • To process the request synchronously, specify respond-sync. The POST response contains the final result of the referenced payout.

Pass these parameters in the request body:

  • reference_id. The transaction ID for the payout. The pay for order call generates a webhook, which returns the transaction ID.

  • reference_type. Set to TRANSACTION_ID to the type of 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" \
    -H "Prefer: respond-sync" \
    -d '{
        "reference_id": "29N36144XH0198422",
        "reference_type": "TRANSACTION_ID"
}'

A successful request returns 200 Success 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:

  • 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.

  • 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 fees are deducted from the merchant’s funds.

Congratulations

You have set up orders.