Instant Payouts

You can use the Orders API to instantly pay out orders to your sellers.

Integration steps

  1. Before you can integrate Instant Payouts, you must set up your development environment. After you get a token that lets you access protected REST API resources, you create sandbox accounts to test your web and mobile apps. For details, see Get Started.

    Then, return to this page to integrate Instant Payouts.

  2. Complete an order.
  3. Get order details.

Complete an order

To execute a payment for an order, pass the order ID as a path parameter to POST v2/checkout/orders/{order_id}/capture.

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

Request sample

curl -v -k -X POST 'https://api.paypal.com/v2/checkout/orders/5O190127TN364715T/capture' \
  -H 'PayPal-Request-Id: 7b92603e-77ed-4896-8e78-5dea2050476a' \
  -H "PayPal-Partner-Attribution-Id: Example_Marketplace" \
  -H 'Authorization: Bearer Access-Token \
  -H 'Content-Type: application/json' \
  -d '{}'

Response sample

A successful request returns the HTTP 201 Created status code and a JSON response body that shows order details, including the id field, which is the seller's transaction ID. Use this ID to complete other operations on the captured payment, such as refund or chargeback a captured payment.

{
"id": "5O190127TN364715T",
"status": "COMPLETED",
"payer": {
  "name": {
    "given_name": "John",
    "surname": "Doe"
  },
  "email_address": "customer@example.com",
  "payer_id": "QYR5Z8XDVJNXQ",
  "phone": {
    "phone_number": {
      "national_number": "8882211161"
    }
  },
  "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"
  }
},
"purchase_units": [{
  "reference_id": "d9f80740-38f0-11e8-b467-0ed5f89f718b",
  "shipping": {
    "method": "United States Postal Service",
    "name": {
      "full_name": "John Williams"
    },
    "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": "3C679366HH908993F",
      "status": "COMPLETED",
      "amount": {
        "currency_code": "USD",
        "value": "100.00"
      },
      "seller_protection": {
        "status": "ELIGIBLE",
        "dispute_categories": [
          "ITEM_NOT_RECEIVED",
          "UNAUTHORIZED_TRANSACTION"
        ]
      },
      "final_capture": true,
      "seller_receivable_breakdown": {
        "gross_amount": {
          "currency_code": "USD",
          "value": "100.00"
        },
        "paypal_fee": {
          "currency_code": "USD",
          "value": "3.00"
        },
        "payment_instruction": {
          "platform_fees": [{
            "amount": {
              "currency_code": "USD",
              "value": "25.00"
            },
            "payee": {
              "email_address": "fee@example.com"
            }
          }]
        },
        "net_amount": {
          "currency_code": "USD",
          "value": "72.00"
        }
      },
      "disbursement_mode": "INSTANT",
      "create_time": "2018-04-01T21:20:49Z",
      "update_time": "2018-04-01T21:20:49Z",
      "links": [{
          "href": "https://api.paypal.com/v2/payments/captures/3C679366HH908993F",
          "rel": "self",
          "method": "GET"
        },
        {
          "href": "https://api.paypal.com/v2/payments/captures/3C679366HH908993F/refund",
          "rel": "refund",
          "method": "POST"
        }
      ]
    }]
  }
}],
"links": [{
  "href": "https://api.paypal.com/v2/checkout/orders/5O190127TN364715T",
  "rel": "self",
  "method": "GET"
}]
}

Get order details

To get order details, pass the order ID as a path parameter in a GET /v2/checkout/orders/{order_id} call.

Sample request

curl -v -k -X GET 'https://api.sandbox.paypal.com/v2/checkout/orders/5O190127TN364715T' \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer Access-Token"

Sample response

A successful request returns the HTTP 200 OK status code and a JSON response body that shows order details:

{
  "id": "5O190127TN364715T",
  "status": "COMPLETED",
  "intent": "CAPTURE",
  "gross_amount": {
    "currency_code": "USD",
    "value": "100.00"
  },
  "payer": {
    "name": {
      "given_name": "John",
      "surname": "Doe"
    },
    "email_address": "customer@example.com",
    "payer_id": "QYR5Z8XDVJNXQ",
    "phone": {
      "phone_number": {
        "national_number": "8882211161"
      }
    },
    "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"
    }
  },
  "purchase_units": [
    {
      "reference_id": "d9f80740-38f0-11e8-b467-0ed5f89f718b",
      "amount": {
        "currency_code": "USD",
        "value": "100.00"
      },
      "payee": {
        "email_address": "merchant@example.com"
      },
      "payment_instruction": {
        "disbursement_mode": "DELAYED",
        "platform_fees": [
          {
            "amount": {
              "currency_code": "USD",
              "value": "25.00"
            },
            "payee": {
              "email_address": "fee@example.com"
            }
          }
        ]
      },
      "shipping": {
        "method": "United States Postal Service",
        "name": {
          "full_name": "John Williams"
        },
        "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": "3C679366HH908993F",
            "status": "COMPLETED",
            "amount": {
              "currency_code": "USD",
              "value": "100.00"
            },
            "seller_protection": {
              "status": "ELIGIBLE",
              "dispute_categories": [
                "ITEM_NOT_RECEIVED",
                "UNAUTHORIZED_TRANSACTION"
              ]
            },
            "final_capture": true,
            "seller_receivable_breakdown": {
              "gross_amount": {
                "currency_code": "USD",
                "value": "100.00"
              },
              "paypal_fee": {
                "currency_code": "USD",
                "value": "3.00"
              },
              "platform_fees": [
                {
                  "amount": {
                    "currency_code": "USD",
                    "value": "25.00"
                  },
                  "payee": {
                    "email_address": "fee@example.com"
                  }
                }
              ],
              "net_amount": {
                "currency_code": "USD",
                "value": "72.00"
              }
            },
            "create_time": "2018-04-01T21:20:49Z",
            "update_time": "2018-04-01T21:20:49Z",
            "links": [
              {
                "href": "https://api.paypal.com/v2/payments/captures/3C679366HH908993F",
                "rel": "self",
                "method": "GET"
              },
              {
                "href": "https://api.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.paypal.com/v2/checkout/orders/5O190127TN364715T",
      "rel": "self",
      "method": "GET"
    }
  ]
}
Feedback