On this page
No Headings
Last updated: June 16, 2026
Upgrade your existing integration of the PayPal Commerce Platform to use version 2 of the Orders and Payments API. The upgrade enables you to leverage the existing features you've been using and gives you the following additional functionality:
While there's no change in the overall integration pattern for creating orders or buyer approval, checkout is complete as soon as the Complete Order API is called with a capture-id sent in the response. Version 2 of orders does not support asynchronous calls.
Orders API endpoints are now at /v2/checkout/orders and are noted in the appropriate calls in the v2 integration guide. Notable difference is with the pay for an order call. Pay for an Order is now Capture Payment for an Order: /v2/checkout/orders/{id}/capture.
Payments API endpoints are now at /v2/payments. Notable difference is with the refund endpoint. Refund an Order is now at /v2/payments/captures/{id}/refund.
Several existing sub-resources have some redefinition and other sub-resources are new additions:
| Sub-resource | State and location |
|---|---|
address | Moved under the shipping sub-resource |
city | Replaced with admin_area_2 under address |
state | Replaced with admin_area_1 under address |
disbursement_mode | Moved from the root to inside the purchase_unit of the v2 Create Order call within the payment_instruction |
amount | Redefined with a breakdown |
payment_details | Renamed to payment_instruction and moved from the root into purchase_units |
gross_total_amount | Renamed as amount |
partner_fee | Generalized under platform_fees within payment_instruction |
payer-info | Renamed as payer |
Note: Orders v2 currently supports only one (1) purchase_units.
A reduced response payload containing only new information. If you need the full response payload, pass "Prefer": "return=representation" in the headers of your request.
During the create order call, the intent value should be set to CAPTURE.
You can now update an order using a PATCH endpoint.
To use the latest versions of the API, you'll need to have your account manager update the scopes added to your API credentials. Use of the v2 API will result in the HTTP status code of 401 Unauthorized, even in sandbox, until your account is updated.
To update your create orders calls:
/v2/checkout/orders.intent property with a value of CAPTURE.payment_instruction under platform_fees.payment_instruction.curl -v -k POST https://api-m.sandbox.paypal.com/v1/checkout/orders -H 'PayPal-Partner-Attribution-Id: EXAMPLE_MP' -H 'Content-Type: application/json' -H "Authorization: Bearer Access-Token" -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"
}
}'{
"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-m.paypal.com/v1/checkout/orders/8RU61172JS455403V",
"rel": "self",
"method": "GET"
},
{
"href": "https://api-m.sandbox.paypal.com/webapps/hermes?token=8RU61172JS455403V",
"rel": "approval_url",
"method": "GET"
},
{
"href": "https://api-m.paypal.com/v1/checkout/orders/8RU61172JS455403V",
"rel": "cancel",
"method": "DELETE"
}
],
"status": "CREATED"
}Pay an order is now capture an order. To upgrade your pay an order calls to capture an order:
/v2/checkout/orders/{order_id}/capture.disbursement_mode and payer are now now sent in the Create Order call.payment_source object in the request body when initiating a transaction from a vaulted payment method such as a billing agreement.curl -v https://api-m.sandbox.paypal.com/v1/checkout/orders/5O190127TN364715T/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": "INSTANT"
}{
"order_id": "5O190127TN364715T",
"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-m.paypal.com/v1/checkout/orders/8RU61172JS455403V",
"rel": "self",
"method": "GET"
}]
}The request to show an order is the same. The URL of the endpoint is now /v2/checkout/orders/{order_id}. The response has changed slightly.
{
"id": "8SC68793353299025",
"status": "CREATED",
"gross_total_amount": {
"value": "1.44",
"currency": "USD"
},
"application_context": {},
"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",
"status": "NOT_PROCESSED"
}],
"redirect_urls": {
"return_url": "https://example.com/return",
"cancel_url": "https://example.com/cancel"
},
"links": [{
"href": "https://api-m.sandbox.paypal.com/v1/checkout/orders/8SC68793353299025",
"rel": "self",
"method": "GET"
},
{
"href": "https://api-m.sandbox.paypal.com/checkoutnow?token=8SC68793353299025",
"rel": "approval_url",
"method": "REDIRECT"
}
],
"create_time": "2018-09-21T17:22:45Z"
}The /v2/payments/captures/{id}/refund endpoint is now the endpoint for all post-payment operations. You can use this endpoint with any existing orders created using the v1 endpoint.
These samples show a full refund.
curl -v -X POST https://api-m.sandbox.paypal.com/v1/payments/capture/3CB62566PT644045J/refund
-H "Authorization: Bearer Access-Token"
-H "Content-Type: application/json"{
"id": "1JU08902781691411",
"status": "COMPLETED",
"links": [
{
"rel": "self",
"method": "GET",
"href": "https://api-m.paypal.com/v1/payments/refunds/1JU08902781691411"
},
{
"rel": "up",
"method": "GET",
"href": "https://api-m.paypal.com/v1/payments/captures/2GG279541U471931P"
}
]
}The new synchronous nature of the call change in v2 means there are slight differences in the payment webhooks sent.
| v1 Webhooks | v2 Webhooks |
|---|---|
Response: 200 OK | Response: 201 Created |
CHECKOUT.ORDER.PROCESSED is sent when the order gets picked up from the queue and processed along with the order status. | CHECKOUT.ORDER.COMPLETED is sent when the order status gets moved to COMPLETED upon a successful order/capture call. |
PAYMENT.CAPTURE.DENIED is sent when the payment is denied. | None. An appropriate HTTP error response code is sent on the order/capture call. |
PAYMENT.CAPTURE.COMPLETED is sent whenever the payment is successfully processed. | Same. |
PAYMENT.CAPTURE.REFUNDED is sent whenever a payment has been refunded. | Same. |
For more information on the v2 API and their endpoints, see: