Orders API v1 → v2 integration upgrade guide

Upgrade your existing PayPal Orders API v1 integration to v2.

The Orders API is a server-side API for creating a checkout order and capturing or authorizing payment after the buyer approves it. Orders v2 introduces a unified payment_source model for PayPal, cards, Google Pay, and Apple Pay.

If you currently use v1, upgrading to v2 provides safer retries with idempotency keys, webhooks in place of IPN, and support for order updates and shipment tracking after checkout. Follow this migration guide to update your endpoint URLs and request and response field shapes, and adapt to new operation semantics, status values, and notification mechanisms for v2.

Audience: This guide is for developers and integration engineers migrating an existing Orders v1 integration to v2. It assumes familiarity with the Orders API, OAuth 2.0, and your own codebase's current v1 implementation.

Migration snapshot

• Effort: Tier 1, structural refactor, plus 2 gaps to resolve first.
• Auth changes: None. Same OAuth 2.0.
• Platform enrollment: None required for most integrations. payment_instruction fields (platform_fees, disbursement_mode) require PayPal Complete Payments Platform approval.
• Endpoints migrated: 8 operations.

Prerequisites

• An existing Orders v1 integration to audit and migrate.
• OAuth 2.0 client credentials for both sandbox and live. Sandbox credentials do not work in the live environment.
• Sandbox buyer and seller accounts, created at developer.paypal.com.
• Use api-m.sandbox.paypal.com as the base URL for all testing before go-live.
• PayPal Complete Payments Platform enrollment, only if your integration uses partner_fee_details or disbursement_mode. Most integrations do not need this.

Resolve two gaps before you begin

1. Cancel order has no v2 equivalent: DELETE /v1/checkout/orders/{id} does not exist in v2. If your integration cancels orders, redesign that flow before migrating.
2. POST .../pay has been split: The single v1 "pay" call becomes either POST .../capture or POST .../authorize depending on your order intent. This is a flow change, not a rename.

Step 1: Review your current integration

Search strings

Find in your project:

• /v1/checkout/orders
• POST /v1/checkout/orders
• DELETE /v1/checkout/orders/
• /v1/checkout/orders/{id}/pay
• intent.*SALE
• disbursement_mode
• notify_url
• partner_fee_details
• payment_linked_group
• gross_total_amount
• supplementary_data
• risk_correlation_id
• redirect_urls
• approval_url
• payment_summary
• payer_info

What carries forward

Step 2: Full API surface mapping

The endpoint mapping and field-level mapping tables in this section map every v1 endpoint, request field, and response field to its v2 equivalent.

Endpoint mapping

Request field mapping (create order)

Response field mapping

Step 3: Update create order

Update your create order request field by field, starting with the intent value.

Intent: SALE to CAPTURE

Most common migration failure: Sending "intent": "SALE" to the v2 endpoint returns a 400 Bad Request validation error. This is the highest-frequency mistake in this migration.

v1:

{ "intent": "SALE" }

v2:

{ "intent": "CAPTURE" }

Redirect URLs, moved into payment_source.{source}.experience_context

v1 sends return_url and cancel_url at the top level of the request. v2 nests them inside experience_context under the specific payment source.

v1, top-level (required):

{
  "redirect_urls": {
    "return_url": "https://.../return",
    "cancel_url": "https://.../cancel"
  }
}

v2, per payment source (examples):

// PayPal Wallet
"payment_source": {
  "paypal": {
    "experience_context": {
      "return_url": "https://.../return",
      "cancel_url": "https://.../cancel"
    }
  }
}

// Google Pay
"payment_source": {
  "google_pay": {
    "experience_context": {
      "return_url": "https://.../return",
      "cancel_url": "https://.../cancel"
    }
  }
}

// Apple Pay
"payment_source": {
  "apple_pay": {
    "experience_context": {
      "return_url": "https://.../return",
      "cancel_url": "https://.../cancel"
    }
  }
}

// Card
"payment_source": {
  "card": {
    "experience_context": {
      "return_url": "https://.../return",
      "cancel_url": "https://.../cancel"
    }
  }
}

Amount structure: v1 compared to v2

v2 renames amount.total and amount.currency to value and currency_code, and moves the breakdown fields into Money objects nested under breakdown.

v1:

{
  "amount": {
    "currency": "USD",
    "total": "107.47",
    "details": {
      "subtotal": "99.99",
      "tax": "5.48",
      "shipping": "2.00"
    }
  }
}

v2:

{
  "amount": {
    "currency_code": "USD",
    "value": "107.47",
    "breakdown": {
      "item_total": {
        "currency_code": "USD",
        "value": "99.99"
      },
      "tax_total": {
        "currency_code": "USD",
        "value": "5.48"
      },
      "shipping": {
        "currency_code": "USD",
        "value": "2.00"
      }
    }
  }
}

Item fields: v1 compared to v2

v2 restructures item pricing into a unit_amount object with currency_code, replacing the flat price and currency strings from v1.

v1:

{
  "name": "NeoPhone",
  "sku": "sku03",
  "price": "99.99",
  "currency": "USD",
  "quantity": "1",
  "tax": "5.00"
}

v2:

{
  "name": "NeoPhone",
  "sku": "sku03",
  "unit_amount": {
    "currency_code": "USD",
    "value": "99.99"
  },
  "tax": {
    "currency_code": "USD",
    "value": "5.00"
  },
  "quantity": "1",
  "category": "PHYSICAL_GOODS"
}

Shipping address: v1 compared to v2

v2 renames shipping_address to shipping.address and separates recipient_name into its own shipping.name object.

v1:

{
  "shipping_address": {
    "recipient_name": "John Doe",
    "line1": "2211 N First Street",
    "line2": "Building 17",
    "city": "San Jose",
    "state": "CA",
    "postal_code": "95131",
    "country_code": "US"
  }
}

v2:

{
  "shipping": {
    "name": {
      "full_name": "John Doe"
    },
    "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"
    }
  }
}

Partner fee

The following requests show how partner_fee_details in v1 maps to the payment_instruction.platform_fees[] array in v2.

v1:

{
  "partner_fee_details": {
    "receiver": {
      "email": "[email protected]"
    },
    "amount": {
      "currency": "USD",
      "value": "1.00"
    }
  }
}

v2:

{
  "payment_instruction": {
    "platform_fees": [
      {
        "amount": {
          "currency_code": "USD",
          "value": "1.00"
        },
        "payee": {
          "email_address": "[email protected]"
        }
      }
    ]
  }
}

Disbursement mode, moved to create time

Timing change: In v1, you sent disbursement_mode in the body of a POST .../pay request at execute time. In v2, you need to set disbursement_mode in the purchase_units[].payment_instruction object when you create the order. If you pass disbursement_mode in the body of a v2 capture request, the API accepts the value but doesn't apply it.

v2, set on create order:

{
  "purchase_units": [
    {
      "payment_instruction": {
        "disbursement_mode": "DELAYED"
      }
    }
  ]
}

supplementary_data (risk_correlation_id), moved to request header

v1, request body:

{
  "application_context": {
    "supplementary_data": [
      {
        "name": "risk_correlation_id",
        "value": "9N8554567F903282T"
      },
      {
        "name": "buyer_ipaddress",
        "value": "109.20.212.116"
      },
      {
        "name": "external_channel",
        "value": "WEB"
      }
    ]
  }
}

v2, request header:

PayPal-Client-Metadata-Id: 9N8554567F903282T

Create order request: complete v1 and v2 comparison

The following requests apply every field-level change from this step together, from a complete v1 create order call to its v2 equivalent.

v1, create order:

POST /v1/checkout/orders

{
  "intent": "SALE",
  "redirect_urls": {
    "return_url": "https://example.com/return",
    "cancel_url": "https://example.com/cancel"
  },
  "purchase_units": [
    {
      "reference_id": "order_1234",
      "custom": "my-internal-ref",
      "invoice_number": "INV-001",
      "amount": {
        "currency": "USD",
        "total": "107.47",
        "details": {
          "subtotal": "99.99",
          "tax": "5.48",
          "shipping": "2.00"
        }
      },
      "items": [
        {
          "name": "NeoPhone",
          "sku": "sku03",
          "price": "99.99",
          "currency": "USD",
          "quantity": "1"
        }
      ],
      "shipping_address": {
        "recipient_name": "John Doe",
        "line1": "2211 N First Street",
        "city": "San Jose",
        "state": "CA",
        "postal_code": "95131",
        "country_code": "US"
      }
    }
  ]
}

v2, create order:

Replace "paypal" with "google_pay", "apple_pay", or "card" as needed. The experience_context object nests the same way for each.

POST /v2/checkout/orders

{
  "intent": "CAPTURE",
  "payment_source": {
    "paypal": {
      "experience_context": {
        "return_url": "https://example.com/return",
        "cancel_url": "https://example.com/cancel"
      }
    },
    // Replace "paypal" with "google_pay", "apple_pay", or "card"
    // as needed. experience_context nests the same way for each.
  },
  "purchase_units": [
    {
      "reference_id": "order_1234",
      "custom_id": "my-internal-ref",
      "invoice_id": "INV-001",
      "amount": {
        "currency_code": "USD",
        "value": "107.47",
        "breakdown": {
          "item_total": {
            "currency_code": "USD",
            "value": "99.99"
          },
          "tax_total": {
            "currency_code": "USD",
            "value": "5.48"
          },
          "shipping": {
            "currency_code": "USD",
            "value": "2.00"
          }
        }
      },
      "items": [
        {
          "name": "NeoPhone",
          "sku": "sku03",
          "unit_amount": {
            "currency_code": "USD",
            "value": "99.99"
          },
          "quantity": "1",
          "category": "PHYSICAL_GOODS"
        }
      ],
      "shipping": {
        "name": {
          "full_name": "John Doe"
        },
        "address": {
          "address_line_1": "2211 N First Street",
          "admin_area_2": "San Jose",
          "admin_area_1": "CA",
          "postal_code": "95131",
          "country_code": "US"
        }
      }
    }
  ]
}

Step 4: Update order execution

The single v1 pay call splits into two dedicated v2 endpoints, capture or authorize, depending on your order's intent.

The split

Capture, replaces SALE to pay

v1 finalizes a SALE-intent order with a POST .../pay call. v2 replaces it with a dedicated capture endpoint that takes an empty body.

v1:

POST /v1/checkout/orders/{id}/pay

{
  "disbursement_mode": "INSTANT"
}

v2:

POST /v2/checkout/orders/{id}/capture

{}

The capture body is empty, or contains only payment_source for advanced flows. Set the disbursement_mode at order creation time instead.

Authorize, replaces AUTHORIZE to pay

v1 finalizes an AUTHORIZE-intent order with the same POST .../pay call. v2 replaces it with a dedicated authorize endpoint, followed by a separate call to capture the authorization.

v1:

POST /v1/checkout/orders/{id}/pay

{
  "disbursement_mode": "INSTANT"
}

v2:

POST /v2/checkout/orders/{id}/authorize

{}

# Then capture the authorization:
POST /v2/payments/authorizations/{auth_id}/capture

Step 5: Handle the cancel order gap

Available strategies:

• Do nothing for abandonment: Orders that are never approved or captured expire automatically. For example, when you cancel an order as a defensive cleanup in response to user abandonment, the order expires automatically.
• Cancel in your system only: Record the cancellation server-side and decline to call capture or authorize. The order expires without any further API calls.
• Update CANCELED status references: This status does not exist in v2. Update any business logic or database state machines that rely on a CANCELED order status.

Step 6: Migrate from IPN to webhooks

Register a webhook

POST /v1/notifications/webhooks

{
  "url": "https://your-server.com/paypal-webhook",
  "event_types": [
    { "name": "CHECKOUT.ORDER.APPROVED" },
    { "name": "PAYMENT.CAPTURE.COMPLETED" },
    { "name": "PAYMENT.CAPTURE.PENDING" },
    { "name": "PAYMENT.CAPTURE.DENIED" },
    { "name": "PAYMENT.CAPTURE.REFUNDED" },
    { "name": "PAYMENT.AUTHORIZATION.CREATED" },
    { "name": "PAYMENT.AUTHORIZATION.VOIDED" }
  ]
}

Event mapping

Signature verification

Always verify webhook payloads before processing. Do not reuse IPN validation logic.

POST /v1/notifications/verify-webhook-signature

{
  "auth_algo": "SHA256withRSA",
  "cert_url": "...",
  "transmission_id": "...",
  "transmission_sig": "...",
  "transmission_time": "...",
  "webhook_id": "your-webhook-id",
  "webhook_event": { /* full event payload */ }
}

Step 7: Response structure changes

Several response fields change shape or value between v1 and v2, starting with how the API returns payer information.

Payer information: v1 compared to v2

v2 renames the payer_info object to payer and nests the buyer's name under a name object instead of separate first_name and last_name fields.

v1, payer_info:

{
  "payer_info": {
    "email": "[email protected]",
    "first_name": "John",
    "last_name": "Doe",
    "payer_id": "HPQAUP5WC3J8U"
  }
}

v2, payer:

{
  "payer": {
    "email_address": "[email protected]",
    "name": {
      "given_name": "John",
      "surname": "Doe"
    },
    "payer_id": "HPQAUP5WC3J8U"
  }
}

HATEOAS approval link

The v1 rel: "approval_url" link is replaced in v2, but the exact replacement rel depends on how the order was created:

The following responses show the exact rel value returned in each scenario from preceding table.

v1:

{ "rel": "approval_url" }

v2, without payment_source:

{ "rel": "approve" }

v2, with payment_source:

{ "rel": "payer-action" }

Order status values

Step 8: New v2 capabilities to adopt

Step 9: Testing

Sandbox setup: Use api-m.sandbox.paypal.com. Create sandbox buyer and seller accounts at developer.paypal.com. Sandbox OAuth credentials do not work in the live environment.

Step 10: Go live

• Switch base URL to api-m.paypal.com.
• Replace sandbox OAuth credentials with live client ID and secret.
• All intent: "SALE" replaced with intent: "CAPTURE".
• All POST .../pay calls replaced with capture or authorize.
• disbursement_mode set at create time, not capture time. Skip this item if it doesn't apply to your integration. PayPal Complete Payments Platform only.
• IPN endpoints decommissioned. Live webhook listeners active and verified.
• notify_url removed from all create order requests.
• Cancel order logic updated or removed.
• Log debug_id from all non-2xx responses for PayPal support escalation.

Migration checklist

• Update base URL from /v1/checkout/orders to /v2/checkout/orders.
• Replace intent: "SALE" with intent: "CAPTURE".
• Move redirect_urls.return_url and cancel_url into payment_source.{source}.experience_context where {source} is paypal, google_pay, apple_pay, or card.
• Move application_context.brand_name to payment_source.{source}.experience_context.brand_name.
• Move application_context.locale to payment_source.{source}.experience_context.locale.
• Move application_context.shipping_preference to payment_source.{source}.experience_context.shipping_preference.
• Move application_context.user_action to payment_source.{source}.experience_context.user_action. Rename the value "commit" to "PAY_NOW".
• Remove application_context from create order requests entirely. Use experience_context per payment source instead.
• Replace supplementary_data[name="risk_correlation_id"] body entry with the PayPal-Client-Metadata-Id request header.
• Remove supplementary_data entries for buyer_ipaddress and external_channel. No v2 equivalent exists.
• Rename amount.currency to amount.currency_code.
• Rename amount.total to amount.value.
• Rename amount.details to amount.breakdown. Convert all sub-fields to Money objects.
• Convert item price and currency to unit_amount.value and unit_amount.currency_code.
• Convert item tax string to a Money object with currency_code.
• Rename shipping_address to shipping.address. Rename all address sub-fields to match.
• Move recipient_name to shipping.name.full_name.
• Rename custom to custom_id in all purchase units.
• Replace POST .../pay with POST .../capture for CAPTURE intent.
• Replace POST .../pay with POST .../authorize for AUTHORIZE intent.
• Remove disbursement_mode from the capture body. Set it on create in payment_instruction instead. This requires PayPal Complete Payments Platform enrollment. See Get Started with Multiparty.
• Replace partner_fee_details with payment_instruction.platform_fees[]. This requires PayPal Complete Payments Platform enrollment. See Get Started with Multiparty.
• Update response parsing: change payment_summary to payments and payer_info to payer.
• Update HATEOAS rel navigation: change approval_url to approve when there's no payment_source, or to payer-action when payment_source is present. Navigate dynamically, and never hardcode either value.
• Update order status handling for renamed states (FAILED to VOIDED).
• Remove all notify_url fields. Register and verify webhooks.
• Update or remove cancel order logic. v2 has no cancel endpoint.
• Add the PayPal-Request-Id header on create, capture, and authorize calls.
• Run all test scenarios in sandbox.
• Switch base URL and credentials to live.

Avoid these common migration pitfalls

These are the mistakes developers make most often during this migration. Check your integration against each one.

1. Sending intent: "SALE" to v2

Mistake: Passing "intent": "SALE" unchanged from v1 to the v2 create order endpoint.

Why it happens: The field name is identical; only the value changed.

Resolution: v2 returns a 400 Bad Request validation error. Replace with "CAPTURE". This is the most frequent migration failure in live cutover.

2. Still calling POST .../pay

Mistake: Updating the base URL to v2 but keeping the /pay path.

Why it happens: Developers update the host but not the operation-specific path.

Resolution: The pay endpoint does not exist in v2. Route to /capture or /authorize based on the order's intent. v2 returns 404 for the old path.

3. Setting disbursement_mode on capture

Mistake: Sending disbursement_mode in the capture request body as in v1.

Resolution: Set disbursement_mode in purchase_units[].payment_instruction.disbursement_mode on create order or using PATCH before capture. If you send disbursement_mode on the capture call instead, the API either accepts the value without applying it or returns a validation error, depending on the request. The payment_instruction and disbursement_mode objects are available to PayPal Complete Payments Platform accounts only. If PayPal hasn't approved your account, this field is not available regardless of where you send it. See Get Started with Multiparty.

4. Hardcoding a specific rel value to extract the approval URL

Mistake: Filtering HATEOAS links for a hardcoded rel string, whether "approval_url" (v1), "approve", or "payer-action".

Why it happens: v1 always returned "approval_url". In v2, the rel is conditional: "approve" is returned when the order is created without a payment_source, and "payer-action" is returned when a payment_source is included. Developers who only test one path miss the other.

Resolution: Navigate HATEOAS links dynamically. If your integration creates orders both with and without a payment_source, your redirect logic needs to handle both "approve" and "payer-action". If your redirect logic filters for only one rel value, it fails to find a match for the other integration pattern, and no error surfaces to indicate why.

5. Calling DELETE to cancel an order

Mistake: Calling DELETE /v2/checkout/orders/{id} expecting a 204.

Resolution: v2 returns 404. Remove or reroute cancel logic. Orders expire naturally; explicit cancellation is not required and not supported.

6. Parsing payment_summary instead of payments

Mistake: Reading capture IDs from purchase_units[].payment_summary.captures[0].id.

Resolution: In v2, captures are at purchase_units[].payments.captures[0].id. Orders v2 renames the payment_summary object to payments. When you pass the wrong path, the API returns undefined without throwing an error, making this easy to miss.

7. Amount breakdown validation failures

Mistake: Setting amount.value to a number that doesn't equal the sum of breakdown components.

Why it happens: v1's amount.details was informational and not validated server-side. v2 enforces this sum.

Resolution: v2 returns 422 Unprocessable Entity on mismatch. Validate item_total + tax_total + shipping + handling + insurance - shipping_discount - discount = value before calling the API.

8. Expecting IPN delivery via notify_url

Mistake: Including notify_url in v2 create order requests and waiting for IPN callbacks.

Resolution: If you include notify_url in a v2 request, the API accepts the field but never sends an IPN. Register webhooks and validate that PAYMENT.CAPTURE.COMPLETED events are received before removing v1 IPN listeners from live traffic.

9. Reading payer_info in v2 responses

Mistake: Reading payer details from response.payer_info.first_name in v2.

Resolution: v2 uses payer.email_address, payer.name.given_name, and payer.name.surname. The payer_info object does not exist in v2 responses.

10. Sending v1 address field names to v2

Mistake: Sending shipping_address.city, shipping_address.state, and shipping_address.line1 to v2.

Resolution: v2 address fields are shipping.address.address_line_1, admin_area_2 (city), and admin_area_1 (state or province). If you send v1 field names instead, the API either discards the unrecognized fields without applying them or returns a validation error for any field it requires.