Receive updated order information via callback URL

The documentation for this 'endpoint' is different from the other endpoints under v2 Orders. For this endpoint the role of client and server is reversed. The client sending the request is PayPal, and the server sending the response is the merchant. In the request, PayPal will send the buyer's redacted shipping address and selected shipping option to the callback URL defined the create order request. The response from the merchant will update the Orders resource.

Authorization

AuthorizationBearer <token>

Oauth 2.0 authentication

FlowClient CredentialsToken URLhttps://api-m.sandbox.paypal.com/v1/oauth2/tokenInheader

Scopes

Manage payments and checkout workflow.https://uri.paypal.com/services/payments/payment

Header Parameters

Authorization?Schema Object for standard headers

Holds authorization information for external API calls.

Match^.*$

Length1 <= length <= 16000

PayPal-Transmission-Id*string

The unique ID of the HTTP transmission.

Match^(?!\d+$)\w+\S+$

Length1 <= length <= 50

PayPal-Transmission-Time*string

The date and time of the HTTP transmission, in Internet date and time format.

Match

^[0-9]{4}-(0[1-9]|1[0-2])-(0[1-9]|[1-2][0-9]|3[0-1])[T,t]([0-1][0-9]|2[0-3]):[0-5][0-9]:([0-5][0-9]|60)([.][0-9]+)?([Zz]|[+-][0-9]{2}:[0-9]{2})$

Length20 <= length <= 64

PayPal-Cert-Url*string

The URL to the X.509 public key certificate. The merchant downloads the certificate from this URL and uses it to verify the signature.

Formaturi

Length1 <= length <= 500

PayPal-Transmission-Sig*string

The PayPal-generated asymmetric signature.

Match^(?!\d+$)\w+\S+$

Length1 <= length <= 500

PayPal-Auth-Algo?string

The algorithm that PayPal uses to generate the signature and that the merchant can use to verify the signature.

Match^[a-zA-Z0-9]+$

Length1 <= length <= 100

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Response Body

`application/json`

curl -X POST "https://api-m.sandbox.paypal.com/v2/checkout/orders/order-update-callback" \  -H "Authorization: Bearer A21AAGHr9qtiRRXH4oYcQokQgV99rGqEIfgrr8xHCclP0OzmD9KVgg5ppIIg1jzJgQkV4wd02svIvBJyg6cLFJjFow_SjBhxQ" \  -H "PayPal-Transmission-Id: 69cd13f0-d67a-11e5-baa3-778b53f4ae55" \  -H "PayPal-Transmission-Time: 2016-02-18T20:01:35Z" \  -H "PayPal-Cert-Url: https://api-m.paypal.com/v1/notifications/certs/CERT-1234567890" \  -H "PayPal-Transmission-Sig: lmI95Jx3Y9nhR5SJWlHVIWpg4AgFk7n9bCHSRxbrd8A9zrhdu2rMyFrmz+Zjh3s3boXB07VXCXUZy/UFzUlnGJn0wDugt7FlSvdKeIJenLRemUxYCPVoEZzg9VFNqOa48gMkvF+XTpxBeUx/kWy6B5cp7GkT2+pOowfRK7OaynuxUoKW3JcMWw272VKjLTtTAShncla7tGF+55rxyt2KNZIIqxNMJ48RDZheGU5w1npu9dZHnPgTXB9iomeVRoD8O/jhRpnKsGrDschyNdkeh81BJJMH4Ctc6lnCCquoP/GzCzz33MMsNdid7vL/NIWaCsekQpW26FpWPi/tfj8nLA==" \  -H "PayPal-Auth-Algo: SHA256withRSA" \  -H "Content-Type: application/json" \  -d '{    "id": "8HFTASDATTV",    "shipping_address": {      "country_code": "US",      "admin_area_1": "TX",      "admin_area_2": "Dallas",      "postal_code": "75001"    },    "purchase_units": [      {        "reference_id": "d9f80740-38f0-11e8-b467-0ed5f89f718b",        "amount": {          "currency_code": "USD",          "value": "100.00"        }      }    ]  }'

{
  "id": "8HFTASDATTV",
  "purchase_units": {
    "reference_id": "d9f80740-38f0-11e8-b467-0ed5f89f718b",
    "amount": {
      "currency_code": "USD",
      "value": "105.00",
      "breakdown": {
        "item_total": {
          "currency_code": "USD",
          "value": "100.00"
        },
        "tax_total": {
          "currency_code": "USD",
          "value": "5.00"
        },
        "shipping": {
          "currency_code": "USD",
          "value": "0.00"
        }
      }
    },
    "shipping_options": [
      {
        "id": "1",
        "amount": {
          "currency_code": "USD",
          "value": "0.00"
        },
        "type": "SHIPPING",
        "label": "Free Shipping",
        "selected": true
      },
      {
        "id": "2",
        "amount": {
          "currency_code": "USD",
          "value": "7.00"
        },
        "type": "SHIPPING",
        "label": "USPS Priority Shipping",
        "selected": false
      },
      {
        "id": "3",
        "amount": {
          "currency_code": "USD",
          "value": "10.00"
        },
        "type": "SHIPPING",
        "label": "1-Day Shipping",
        "selected": false
      }
    ]
  }
}

{
  "name": "string",
  "message": "string",
  "details": [
    {
      "field": "string",
      "value": "string",
      "issue": "string"
    }
  ]
}

{
  "name": "string",
  "message": "string",
  "details": [
    {
      "field": "string",
      "value": "string",
      "issue": "string"
    }
  ]
}

{
  "name": "NOT_AUTHORIZED",
  "debug_id": "b1d1f06c7246c",
  "message": "Authorization failed due to insufficient permissions."
}

{
  "name": "UNPROCESSABLE_ENTITY",
  "details": [
    {
      "issue": "ADDRESS_ERROR"
    }
  ]
}

{
  "name": "INTERNAL_SERVER_ERROR",
  "debug_id": "b1d1f06c7246c",
  "message": "An internal server error has occurred."
}

{
  "name": "INTERNAL_SERVER_ERROR",
  "debug_id": "b1d1f06c7246c",
  "message": "An internal server error has occurred."
}

Header Parameters

Authorization?Schema Object for standard headers

Holds authorization information for external API calls.

Match^.*$

Length1 <= length <= 16000

PayPal-Transmission-Id*string

The unique ID of the HTTP transmission.

Match^(?!\d+$)\w+\S+$

Length1 <= length <= 50

PayPal-Transmission-Time*string

The date and time of the HTTP transmission, in Internet date and time format.

Match

^[0-9]{4}-(0[1-9]|1[0-2])-(0[1-9]|[1-2][0-9]|3[0-1])[T,t]([0-1][0-9]|2[0-3]):[0-5][0-9]:([0-5][0-9]|60)([.][0-9]+)?([Zz]|[+-][0-9]{2}:[0-9]{2})$

Length20 <= length <= 64

PayPal-Cert-Url*string

The URL to the X.509 public key certificate. The merchant downloads the certificate from this URL and uses it to verify the signature.

Formaturi

Length1 <= length <= 500

PayPal-Transmission-Sig*string

The PayPal-generated asymmetric signature.

Match^(?!\d+$)\w+\S+$

Length1 <= length <= 500

PayPal-Auth-Algo?string

The algorithm that PayPal uses to generate the signature and that the merchant can use to verify the signature.

Match^[a-zA-Z0-9]+$

Length1 <= length <= 100

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

shipping_address?

shipping_option?

purchase_units*array<>

An array of purchase units. At present only 1 purchase_unit is supported. Each purchase unit establishes a contract between a payer and the payee. Each purchase unit represents either a full or partial order that the payer intends to purchase from the payee.

Items1 <= items <= 1

curl -X POST "https://api-m.sandbox.paypal.com/v2/checkout/orders/order-update-callback" \ -H "Authorization: Bearer A21AAGHr9qtiRRXH4oYcQokQgV99rGqEIfgrr8xHCclP0OzmD9KVgg5ppIIg1jzJgQkV4wd02svIvBJyg6cLFJjFow_SjBhxQ" \ -H "PayPal-Transmission-Id: 69cd13f0-d67a-11e5-baa3-778b53f4ae55" \ -H "PayPal-Transmission-Time: 2016-02-18T20:01:35Z" \ -H "PayPal-Cert-Url: https://api-m.paypal.com/v1/notifications/certs/CERT-1234567890" \ -H "PayPal-Transmission-Sig: lmI95Jx3Y9nhR5SJWlHVIWpg4AgFk7n9bCHSRxbrd8A9zrhdu2rMyFrmz+Zjh3s3boXB07VXCXUZy/UFzUlnGJn0wDugt7FlSvdKeIJenLRemUxYCPVoEZzg9VFNqOa48gMkvF+XTpxBeUx/kWy6B5cp7GkT2+pOowfRK7OaynuxUoKW3JcMWw272VKjLTtTAShncla7tGF+55rxyt2KNZIIqxNMJ48RDZheGU5w1npu9dZHnPgTXB9iomeVRoD8O/jhRpnKsGrDschyNdkeh81BJJMH4Ctc6lnCCquoP/GzCzz33MMsNdid7vL/NIWaCsekQpW26FpWPi/tfj8nLA==" \ -H "PayPal-Auth-Algo: SHA256withRSA" \ -H "Content-Type: application/json" \ -d '{ "id": "8HFTASDATTV", "shipping_address": { "country_code": "US", "admin_area_1": "TX", "admin_area_2": "Dallas", "postal_code": "75001" }, "purchase_units": [ { "reference_id": "d9f80740-38f0-11e8-b467-0ed5f89f718b", "amount": { "currency_code": "USD", "value": "100.00" } } ] }'

{ "id": "8HFTASDATTV", "purchase_units": { "reference_id": "d9f80740-38f0-11e8-b467-0ed5f89f718b", "amount": { "currency_code": "USD", "value": "105.00", "breakdown": { "item_total": { "currency_code": "USD", "value": "100.00" }, "tax_total": { "currency_code": "USD", "value": "5.00" }, "shipping": { "currency_code": "USD", "value": "0.00" } } }, "shipping_options": [ { "id": "1", "amount": { "currency_code": "USD", "value": "0.00" }, "type": "SHIPPING", "label": "Free Shipping", "selected": true }, { "id": "2", "amount": { "currency_code": "USD", "value": "7.00" }, "type": "SHIPPING", "label": "USPS Priority Shipping", "selected": false }, { "id": "3", "amount": { "currency_code": "USD", "value": "10.00" }, "type": "SHIPPING", "label": "1-Day Shipping", "selected": false } ] } }

Receive updated order information via callback URL

200application/json

400application/json

401application/json

403application/json

422application/json

500application/json

defaultapplication/json

Shipping Options Callback Request - Shipping Address Only Event

Shipping Options Callback Request - Shipping Address and Shipping Options Event

Shipping Options Callback - 422 Unprocessable Entity - ADDRESS_ERROR

Shipping Options Callback - 422 Unprocessable Entity - COUNTRY_ERROR

Shipping Options Callback - 422 Unprocessable Entity - METHOD_UNAVAILABLE

Shipping Options Callback - 422 Unprocessable Entity - STATE_ERROR

Shipping Options Callback - 422 Unprocessable Entity - STORE_UNAVAILABLE

Shipping Options Callback - 422 Unprocessable Entity - ZIP_ERROR

On this page

If you accept cookies, we’ll use them to improve and customize your experience and enable our partners to show you personalized PayPal ads when you visit other sites. Manage cookies and learn more

Receive updated order information via callback URL

200application/json

400application/json

401application/json

403application/json

422application/json

500application/json

defaultapplication/json

Shipping Options Callback Request - Shipping Address Only Event

Shipping Options Callback Request - Shipping Address and Shipping Options Event

Shipping Options Callback - 422 Unprocessable Entity - ADDRESS_ERROR

Shipping Options Callback - 422 Unprocessable Entity - COUNTRY_ERROR

Shipping Options Callback - 422 Unprocessable Entity - METHOD_UNAVAILABLE

Shipping Options Callback - 422 Unprocessable Entity - STATE_ERROR

Shipping Options Callback - 422 Unprocessable Entity - STORE_UNAVAILABLE

Shipping Options Callback - 422 Unprocessable Entity - ZIP_ERROR

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`