API Version

Orders API

Use the Orders API to create, update, show details for, authorize and capture payments for, save, and void orders.

Orders (resource group)

Use the /orders resource to create, update, show details for, and authorize and capture payments for orders.

Create order

POST /v2/checkout/orders

Creates an order. Supports orders with only one purchase unit.

Header parameters

For more information about HTTP request headers, see HTTP request headers.

PayPal-Partner-Attribution-Id

string

For more information about PayPal-Partner-Attribution-Id, see PayPal-Partner-Attribution-Id.
Prefer

string
The preferred server response upon successful completion of the request. Value is:
- return=minimal. The server returns a minimal response to optimize communication between the API caller and the server. A minimal response includes the id, status and HATEOAS links.
- return=representation. The server returns a complete resource representation, including the current state of the resource.
Default: return=minimal.
Authorization

string

required

To make REST API calls, include the bearer token in this header with the Bearer authentication scheme. The value is Bearer <Access-Token> or Basic <client_id;secret>.
Content-Type

string

required

Required for operations with a request body. The value is application/. Where the 'format' is 'json'.

Request body

intent

enum

required
The intent to either capture payment immediately or authorize a payment for an order after order creation. The allowed values are:
- CAPTURE. The merchant intends to capture payment immediately after the customer makes a payment.
- AUTHORIZE. The merchant intends to authorize a payment and place funds on hold after the customer makes a payment. Authorized payments are guaranteed for up to three days but are available to capture for up to 29 days. After the three-day honor period, the original authorized payment expires and you must re-authorize the payment. You must make a separate request to capture payments on demand.
payer

object

The customer who approves and pays for the order. The customer is also known as the payer.
purchase_units

array (contains the purchase_unit_request object)

required

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

object

Customize the payer experience during the approval process for the payment with PayPal.

Sample Request

curl -v -X POST https://api.sandbox.paypal.com/v2/checkout/orders \
-H "Content-Type: application/json" \
-H "Authorization: Bearer Access-Token" \
-d '{
  "intent": "CAPTURE",
  "purchase_units": [
    {
      "amount": {
        "currency_code": "USD",
        "value": "100.00"
      }
    }
  ]
}'

Response

A successful request returns the HTTP 201 Created status code and a JSON response body that includes by default a minimal response with the ID, status, and HATEOAS links. If you require the complete order resource representation, you must pass the Prefer: return=representation request header. This header value is not the default.

create_time

string

The date and time when the transaction occurred, in Internet date and time format.

Read only.

Minimum length: 20.

Maximum length: 64.

Pattern: ^[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})$.
update_time

string

The date and time when the transaction was last updated, in Internet date and time format.

Read only.

Minimum length: 20.

Maximum length: 64.

Pattern: ^[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})$.
id

string

The ID of the order.

Read only.
intent

enum
The intent to either capture payment immediately or authorize a payment for an order after order creation. The possible values are:
- CAPTURE. The merchant intends to capture payment immediately after the customer makes a payment.
- AUTHORIZE. The merchant intends to authorize a payment and place funds on hold after the customer makes a payment. Authorized payments are guaranteed for up to three days but are available to capture for up to 29 days. After the three-day honor period, the original authorized payment expires and you must re-authorize the payment. You must make a separate request to capture payments on demand.
payer

object

The customer who approves and pays for the order. The customer is also known as the payer.
purchase_units

array (contains the purchase_unit object)

An array of purchase units. Each purchase unit establishes a contract between a customer and merchant. Each purchase unit represents either a full or partial order that the customer intends to purchase from the merchant.
status

enum
The order status. The possible values are:
- CREATED. The order was created with the specified context.
- SAVED. The order was saved and persisted. The order status continues to be in progress until a capture is made with final_capture = true for all purchase units within the order.
- APPROVED. The customer approved the payment through the PayPal wallet or another form of guest or unbranded payment. For example, a card, bank account, or so on.
- VOIDED. All purchase units in the order are voided.
- COMPLETED. The payment was authorized or the authorized payment was captured for the order.
Read only.
links

array (contains the link_description object)

An array of request-related HATEOAS links. To complete payer approval, use the approve link with the GET method.

Read only.

Sample Response

{
  "id": "5O190127TN364715T",
  "status": "CREATED",
  "links": [
    {
      "href": "https://api.paypal.com/v2/checkout/orders/5O190127TN364715T",
      "rel": "self",
      "method": "GET"
    },
    {
      "href": "https://api.sandbox.paypal.com/checkoutnow?token=5O190127TN364715T",
      "rel": "approve",
      "method": "GET"
    },
    {
      "href": "https://api.paypal.com/v2/checkout/orders/5O190127TN364715T/capture",
      "rel": "capture",
      "method": "POST"
    }
  ]
}

Update order

PATCH /v2/checkout/orders/{order_id}

Updates an order with the CREATED or APPROVED status.
You cannot update an order with the COMPLETED status.
To make an update, you must provide a reference_id.
If you omit a reference_id for an order with one purchase unit, PayPal sets the reference_id to default, which enables you to use a path:

"path": "/purchase_units/@reference_id=='default'/{attribute-or-object}"

.
You can patch these attributes and objects to complete these operations:

intent — replace.
purchase_units — replace, add.
purchase_units[].custom_id — replace, add, remove.
purchase_units[].description — replace, add, remove.
purchase_units[].payee.email — replace, add.
purchase_units[].shipping — replace, add, remove.
purchase_units[].soft_descriptor — replace, add, remove.
purchase_units[].amount — replace.
purchase_units[].invoice_id — replace, add, remove.
purchase_units[].payment_instruction — replace.
Note: You cannot patch this field when you replace a purchase_unit.
purchase_units[].payment_instruction.disbursement_mode — replace.
Note: By default, disbursement_mode is INSTANT.
purchase_units[].payment_instruction.platform_fees — replace, add, remove.

Header parameters

For more information about HTTP request headers, see HTTP request headers.

Authorization

string

required

To make REST API calls, include the bearer token in this header with the Bearer authentication scheme. The value is Bearer <Access-Token> or Basic <client_id;secret>.
Content-Type

string

required

Required for operations with a request body. The value is application/. Where the 'format' is 'json'.

Path parameters

order_id

string

required

The ID of the order to update.

Request body

patch_request

array (contains the patch object)

An array of JSON patch objects to apply partial updates to resources.

Sample Request

curl -v -X PATCH https://api.sandbox.paypal.com/v2/checkout/orders/5O190127TN364715T \
-H "Content-Type: application/json" \
-H "Authorization: Bearer Access-Token" \
-d '[
  {
"op": "add",
"path": "/purchase_units/@reference_id=='PUHF'/invoice_id",
"value": "INV-HighFashions"
  }
]'

Response

A successful request returns the HTTP 204 No Content status code with an empty object in the JSON response body.

Sample Response

204 No Content

Show order details

GET /v2/checkout/orders/{order_id}

Shows details for an order, by ID.

Header parameters

For more information about HTTP request headers, see HTTP request headers.

Authorization

string

required

To make REST API calls, include the bearer token in this header with the Bearer authentication scheme. The value is Bearer <Access-Token> or Basic <client_id;secret>.
Content-Type

string

required

Required for operations with a request body. The value is application/. Where the 'format' is 'json'.

Path parameters

order_id

string

required

The ID of the order for which to show details.

Sample Request

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

Response

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

create_time

string

The date and time when the transaction occurred, in Internet date and time format.

Read only.

Minimum length: 20.

Maximum length: 64.

Pattern: ^[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})$.
update_time

string

The date and time when the transaction was last updated, in Internet date and time format.

Read only.

Minimum length: 20.

Maximum length: 64.

Pattern: ^[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})$.
id

string

The ID of the order.

Read only.
intent

enum
The intent to either capture payment immediately or authorize a payment for an order after order creation. The possible values are:
- CAPTURE. The merchant intends to capture payment immediately after the customer makes a payment.
- AUTHORIZE. The merchant intends to authorize a payment and place funds on hold after the customer makes a payment. Authorized payments are guaranteed for up to three days but are available to capture for up to 29 days. After the three-day honor period, the original authorized payment expires and you must re-authorize the payment. You must make a separate request to capture payments on demand.
payer

object

The customer who approves and pays for the order. The customer is also known as the payer.
purchase_units

array (contains the purchase_unit object)

An array of purchase units. Each purchase unit establishes a contract between a customer and merchant. Each purchase unit represents either a full or partial order that the customer intends to purchase from the merchant.
status

enum
The order status. The possible values are:
- CREATED. The order was created with the specified context.
- SAVED. The order was saved and persisted. The order status continues to be in progress until a capture is made with final_capture = true for all purchase units within the order.
- APPROVED. The customer approved the payment through the PayPal wallet or another form of guest or unbranded payment. For example, a card, bank account, or so on.
- VOIDED. All purchase units in the order are voided.
- COMPLETED. The payment was authorized or the authorized payment was captured for the order.
Read only.
links

array (contains the link_description object)

An array of request-related HATEOAS links. To complete payer approval, use the approve link with the GET method.

Read only.

Sample Response

{
  "id": "5O190127TN364715T",
  "status": "COMPLETED",
  "intent": "CAPTURE",
  "payer": {
    "name": {
      "given_name": "John",
      "surname": "Doe"
    },
    "email_address": "customer@example.com",
    "payer_id": "QYR5Z8XDVJNXQ"
  },
  "purchase_units": [
    {
      "reference_id": "d9f80740-38f0-11e8-b467-0ed5f89f718b",
      "amount": {
        "currency_code": "USD",
        "value": "100.00"
      },
      "payee": {
        "email_address": "merchant@example.com"
      },
      "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,
            "disbursement_mode": "INSTANT",
            "application_context": {
              "supplementary_data": [
                {
                  "industry_type": "AIRLINE",
                  "data": {
                    "airline_itineraries": [
                      {
                        "ticket": {
                          "number": "045-2135145561",
                          "issue_date": "2018-01-19",
                          "issuing_carrier_code": "AI",
                          "travel_agency_name": "World Tours",
                          "travel_agency_code": "01"
                        },
                        "passenger": {
                          "name": {
                            "full_name": "Trini George"
                          },
                          "date_of_birth": "1981-05-31",
                          "country_code": "US"
                        },
                        "flight_leg_details": [
                          {
                            "flight_number": 101,
                            "carrier_code": "AI",
                            "service_class": "J",
                            "departure_date": "2018-02-15",
                            "departure_time": "15:30",
                            "departure_airport": "SFO",
                            "arrival_airport": "DBX",
                            "stopover_code": "X",
                            "fare_basis_code": "SPRSVR"
                          },
                          {
                            "flight_number": 102,
                            "carrier_code": "AI",
                            "service_class": "J",
                            "departure_date": "2018-02-15",
                            "departure_time": "19:05",
                            "departure_airport": "DBX",
                            "arrival_airport": "MAA",
                            "stopover_code": "O",
                            "fare_basis_code": "SPRSVR"
                          }
                        ]
                      }
                    ]
                  }
                }
              ]
            },
            "seller_receivable_breakdown": {
              "gross_amount": {
                "currency_code": "USD",
                "value": "100.00"
              },
              "paypal_fee": {
                "currency_code": "USD",
                "value": "3.00"
              },
              "net_amount": {
                "currency_code": "USD",
                "value": "97.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"
    }
  ]
}

Authorize payment for order

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

Authorizes payment for an order. The response shows details of authorizations. You can make this call only if you specified intent=AUTHORIZE in the create order call.

Header parameters

For more information about HTTP request headers, see HTTP request headers.

PayPal-Request-Id

string

The server stores keys for 45 days. For more information about PayPal-Request-Id, see PayPal-Request-Id.
Prefer

string
The preferred server response upon successful completion of the request. Value is:
- return=minimal. The server returns a minimal response to optimize communication between the API caller and the server. A minimal response includes the id, status and HATEOAS links.
- return=representation. The server returns a complete resource representation, including the current state of the resource.
Default: return=minimal.
PayPal-Client-Metadata-Id

string

For more information about PayPal-Client-Metadata-Id, see PayPal-Client-Metadata-Id.
Authorization

string

required

To make REST API calls, include the bearer token in this header with the Bearer authentication scheme. The value is Bearer <Access-Token> or Basic <client_id;secret>.
PayPal-Auth-Assertion

string

An API-caller-provided JSON Web Token (JWT) assertion that identifies the merchant. For details, see PayPal-Auth-Assertion.
Content-Type

string

required

Required for operations with a request body. The value is application/. Where the 'format' is 'json'.

Path parameters

order_id

string

required

The ID of the order for which to authorize.

Request body

payment_source

object

The source of payment for the order, which can be a token or a card. Use this object only if you have not redirected the user after order creation to approve the payment. In such cases, the user-selected payment method in the PayPal flow is implicitly used.

Sample Request

curl -v -X POST https://api.sandbox.paypal.com/v2/checkout/orders/5O190127TN364715T/authorize \
-H "Content-Type: application/json" \
-H "Authorization: Bearer Access-Token" \
-H "PayPal-Request-Id: 7b92603e-77ed-4896-8e78-5dea2050476a"

Response

A successful response to a non-idempotent request returns the HTTP 201 Created status code with a JSON response body that shows authorized payment details. If a duplicate response is retried, returns the HTTP 200 OK status code. By default, the response is minimal. If you need the complete resource representation, you must pass the Prefer: return=representation request header.

create_time

string

The date and time when the transaction occurred, in Internet date and time format.

Read only.

Minimum length: 20.

Maximum length: 64.

Pattern: ^[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})$.
update_time

string

The date and time when the transaction was last updated, in Internet date and time format.

Read only.

Minimum length: 20.

Maximum length: 64.

Pattern: ^[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})$.
id

string

The ID of the order.

Read only.
intent

enum
The intent to either capture payment immediately or authorize a payment for an order after order creation. The possible values are:
- CAPTURE. The merchant intends to capture payment immediately after the customer makes a payment.
- AUTHORIZE. The merchant intends to authorize a payment and place funds on hold after the customer makes a payment. Authorized payments are guaranteed for up to three days but are available to capture for up to 29 days. After the three-day honor period, the original authorized payment expires and you must re-authorize the payment. You must make a separate request to capture payments on demand.
payer

object

The customer who approves and pays for the order. The customer is also known as the payer.
purchase_units

array (contains the purchase_unit object)

An array of purchase units. Each purchase unit establishes a contract between a customer and merchant. Each purchase unit represents either a full or partial order that the customer intends to purchase from the merchant.
status

enum
The order status. The possible values are:
- CREATED. The order was created with the specified context.
- SAVED. The order was saved and persisted. The order status continues to be in progress until a capture is made with final_capture = true for all purchase units within the order.
- APPROVED. The customer approved the payment through the PayPal wallet or another form of guest or unbranded payment. For example, a card, bank account, or so on.
- VOIDED. All purchase units in the order are voided.
- COMPLETED. The payment was authorized or the authorized payment was captured for the order.
Read only.
links

array (contains the link_description object)

An array of request-related HATEOAS links. To complete payer approval, use the approve link with the GET method.

Read only.

Sample Response

{
  "id": "5O190127TN364715T",
  "status": "COMPLETED",
  "payer": {
    "name": {
      "given_name": "John",
      "surname": "Doe"
    },
    "email_address": "customer@example.com",
    "payer_id": "QYR5Z8XDVJNXQ"
  },
  "purchase_units": [
    {
      "reference_id": "d9f80740-38f0-11e8-b467-0ed5f89f718b",
      "shipping": {
        "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": {
        "authorizations": [
          {
            "id": "0AW2184448108334S",
            "status": "CREATED",
            "amount": {
              "currency_code": "USD",
              "value": "100.00"
            },
            "seller_protection": {
              "status": "ELIGIBLE",
              "dispute_categories": [
                "ITEM_NOT_RECEIVED",
                "UNAUTHORIZED_TRANSACTION"
              ]
            },
            "expiration_time": "2018-05-01T21:20:49Z",
            "create_time": "2018-04-01T21:20:49Z",
            "update_time": "2018-04-01T21:20:49Z",
            "links": [
              {
                "href": "https://api.paypal.com/v2/payments/authorizations/0AW2184448108334S",
                "rel": "self",
                "method": "GET"
              },
              {
                "href": "https://api.paypal.com/v2/payments/authorizations/0AW2184448108334S/capture",
                "rel": "capture",
                "method": "POST"
              },
              {
                "href": "https://api.paypal.com/v2/payments/authorizations/0AW2184448108334S/void",
                "rel": "void",
                "method": "POST"
              },
              {
                "href": "https://api.paypal.com/v2/payments/authorizations/0AW2184448108334S/reauthorize",
                "rel": "reauthorize",
                "method": "POST"
              }
            ]
          }
        ]
      }
    }
  ],
  "links": [
    {
      "href": "https://api.paypal.com/v2/checkout/orders/5O190127TN364715T",
      "rel": "self",
      "method": "GET"
    }
  ]
}

Capture payment for order

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

Captures a payment for an order.

Header parameters

For more information about HTTP request headers, see HTTP request headers.

PayPal-Request-Id

string

The server stores keys for 45 days. For more information about PayPal-Request-Id, see PayPal-Request-Id.
Prefer

string
The preferred server response upon successful completion of the request. Value is:
- return=minimal. The server returns a minimal response to optimize communication between the API caller and the server. A minimal response includes the id, status and HATEOAS links.
- return=representation. The server returns a complete resource representation, including the current state of the resource.
Default: return=minimal.
PayPal-Client-Metadata-Id

string

For more information about PayPal-Client-Metadata-Id, see PayPal-Client-Metadata-Id.
Authorization

string

required

To make REST API calls, include the bearer token in this header with the Bearer authentication scheme. The value is Bearer <Access-Token> or Basic <client_id;secret>.
PayPal-Auth-Assertion

string

An API-caller-provided JSON Web Token (JWT) assertion that identifies the merchant. For details, see PayPal-Auth-Assertion.
Content-Type

string

required

Required for operations with a request body. The value is application/. Where the 'format' is 'json'.

Path parameters

order_id

string

required

The ID of the order for which to capture a payment.

Request body

payment_source

object

The payment source definition.

Sample Request

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

Response

A successful response to a non-idempotent request returns the HTTP 201 Created status code with a JSON response body that shows captured payment details. If a duplicate response is retried, returns the HTTP 200 OK status code. By default, the response is minimal. If you need the complete resource representation, pass the Prefer: return=representation request header.

create_time

string

The date and time when the transaction occurred, in Internet date and time format.

Read only.

Minimum length: 20.

Maximum length: 64.

Pattern: ^[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})$.
update_time

string

The date and time when the transaction was last updated, in Internet date and time format.

Read only.

Minimum length: 20.

Maximum length: 64.

Pattern: ^[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})$.
id

string

The ID of the order.

Read only.
intent

enum
The intent to either capture payment immediately or authorize a payment for an order after order creation. The possible values are:
- CAPTURE. The merchant intends to capture payment immediately after the customer makes a payment.
- AUTHORIZE. The merchant intends to authorize a payment and place funds on hold after the customer makes a payment. Authorized payments are guaranteed for up to three days but are available to capture for up to 29 days. After the three-day honor period, the original authorized payment expires and you must re-authorize the payment. You must make a separate request to capture payments on demand.
payer

object

The customer who approves and pays for the order. The customer is also known as the payer.
purchase_units

array (contains the purchase_unit object)

An array of purchase units. Each purchase unit establishes a contract between a customer and merchant. Each purchase unit represents either a full or partial order that the customer intends to purchase from the merchant.
status

enum
The order status. The possible values are:
- CREATED. The order was created with the specified context.
- SAVED. The order was saved and persisted. The order status continues to be in progress until a capture is made with final_capture = true for all purchase units within the order.
- APPROVED. The customer approved the payment through the PayPal wallet or another form of guest or unbranded payment. For example, a card, bank account, or so on.
- VOIDED. All purchase units in the order are voided.
- COMPLETED. The payment was authorized or the authorized payment was captured for the order.
Read only.
links

array (contains the link_description object)

An array of request-related HATEOAS links. To complete payer approval, use the approve link with the GET method.

Read only.

Sample Response

{
  "id": "5O190127TN364715T",
  "status": "COMPLETED",
  "payer": {
    "name": {
      "given_name": "John",
      "surname": "Doe"
    },
    "email_address": "customer@example.com",
    "payer_id": "QYR5Z8XDVJNXQ"
  },
  "purchase_units": [
    {
      "reference_id": "d9f80740-38f0-11e8-b467-0ed5f89f718b",
      "shipping": {
        "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,
            "disbursement_mode": "INSTANT",
            "seller_receivable_breakdown": {
              "gross_amount": {
                "currency_code": "USD",
                "value": "100.00"
              },
              "paypal_fee": {
                "currency_code": "USD",
                "value": "3.00"
              },
              "net_amount": {
                "currency_code": "USD",
                "value": "97.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"
              }
            ]
          }
        ]
      }
    }
  ],
  "links": [
    {
      "href": "https://api.paypal.com/v2/checkout/orders/5O190127TN364715T",
      "rel": "self",
      "method": "GET"
    }
  ]
}

Common object definitions

activity_timestamps

create_time

string

The date and time when the transaction occurred, in Internet date and time format.

Read only.

Minimum length: 20.

Maximum length: 64.

Pattern: ^[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})$.
update_time

string

The date and time when the transaction was last updated, in Internet date and time format.

Read only.

Minimum length: 20.

Maximum length: 64.

Pattern: ^[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})$.

address_details

street_number

string

The street number.

Maximum length: 100.
street_name

string

The street name. Just Drury in Drury Lane.

Maximum length: 100.
street_type

string

The street type. For example, avenue, boulevard, road, or expressway.

Maximum length: 100.
delivery_service

string

The delivery service. Post office box, bag number, or post office name.

Maximum length: 100.
building_name

string

A named locations that represents the premise. Usually a building name or number or collection of buildings with a common name or number. For example, Craven House.

Maximum length: 100.
sub_building

string

The first-order entity below a named building or location that represents the sub-premise. Usually a single building within a collection of buildings with a common name. Can be a flat, story, floor, room, or apartment.

Maximum length: 100.

address_portable

address_line_1

string

The first line of the address. For example, number or street. For example, 173 Drury Lane. Required for data entry and compliance and risk checks. Must contain the full address.

Maximum length: 300.
address_line_2

string

The second line of the address. For example, suite or apartment number.

Maximum length: 300.
admin_area_2

string

A city, town, or village. Smaller than admin_area_level_1.

Maximum length: 120.
admin_area_1

string
The highest level sub-division in a country, which is usually a province, state, or ISO-3166-2 subdivision. Format for postal delivery. For example, CA and not California. Value, by country, is:
- UK. A county.
- US. A state.
- Canada. A province.
- Japan. A prefecture.
- Switzerland. A kanton.
Maximum length: 300.
postal_code

string

The postal code, which is the zip code or equivalent. Typically required for countries with a postal code or an equivalent. See postal code.

Maximum length: 60.
country_code

string

required

The two-character ISO 3166-1 code that identifies the country or region.
Note: The country code for Great Britain is GB and not UK as used in the top-level domain names for that country. Use the C2 country code for China worldwide for comparable uncontrolled price (CUP) method, bank card, and cross-border transactions.

address_portable

address_line_1

string

The first line of the address. For example, number or street. For example, 173 Drury Lane. Required for data entry and compliance and risk checks. Must contain the full address.

Maximum length: 300.
address_line_2

string

The second line of the address. For example, suite or apartment number.

Maximum length: 300.
admin_area_2

string

A city, town, or village. Smaller than admin_area_level_1.

Maximum length: 120.
admin_area_1

string
The highest level sub-division in a country, which is usually a province, state, or ISO-3166-2 subdivision. Format for postal delivery. For example, CA and not California. Value, by country, is:
- UK. A county.
- US. A state.
- Canada. A province.
- Japan. A prefecture.
- Switzerland. A kanton.
Maximum length: 300.
postal_code

string

The postal code, which is the zip code or equivalent. Typically required for countries with a postal code or an equivalent. See postal code.

Maximum length: 60.
country_code

string

required

The two-character ISO 3166-1 code that identifies the country or region.
Note: The country code for Great Britain is GB and not UK as used in the top-level domain names for that country. Use the C2 country code for China worldwide for comparable uncontrolled price (CUP) method, bank card, and cross-border transactions.

address_portable

address_line_1

string

The first line of the address. For example, number or street. For example, 173 Drury Lane. Required for data entry and compliance and risk checks. Must contain the full address.

Maximum length: 300.
address_line_2

string

The second line of the address. For example, suite or apartment number.

Maximum length: 300.
admin_area_2

string

A city, town, or village. Smaller than admin_area_level_1.

Maximum length: 120.
admin_area_1

string
The highest level sub-division in a country, which is usually a province, state, or ISO-3166-2 subdivision. Format for postal delivery. For example, CA and not California. Value, by country, is:
- UK. A county.
- US. A state.
- Canada. A province.
- Japan. A prefecture.
- Switzerland. A kanton.
Maximum length: 300.
postal_code

string

The postal code, which is the zip code or equivalent. Typically required for countries with a postal code or an equivalent. See postal code.

Maximum length: 60.
country_code

string

required

The two-character ISO 3166-1 code that identifies the country or region.
Note: The country code for Great Britain is GB and not UK as used in the top-level domain names for that country. Use the C2 country code for China worldwide for comparable uncontrolled price (CUP) method, bank card, and cross-border transactions.

address_portable

address_line_1

string

The first line of the address. For example, number or street. For example, 173 Drury Lane. Required for data entry and compliance and risk checks. Must contain the full address.

Maximum length: 300.
address_line_2

string

The second line of the address. For example, suite or apartment number.

Maximum length: 300.
address_line_3

string

The third line of the address, if needed. For example, a street complement for Brazil, direction text, such as next to Walmart, or a landmark in an Indian address.

Maximum length: 100.
admin_area_4

string
The neighborhood, ward, or district. Smaller than admin_area_level_3 or sub_locality. Value is:
- The postal sorting code for Guernsey and many French territories, such as French Guiana.
- The fine-grained administrative levels in China.
Maximum length: 100.
admin_area_3

string
A sub-locality, suburb, neighborhood, or district. Smaller than admin_area_level_2. Value is:
- Brazil. Suburb, bairro, or neighborhood.
- India. Sub-locality or district. Street name information is not always available but a sub-locality or district can be a very small area.
Maximum length: 100.
admin_area_2

string

A city, town, or village. Smaller than admin_area_level_1.

Maximum length: 120.
admin_area_1

string
The highest level sub-division in a country, which is usually a province, state, or ISO-3166-2 subdivision. Format for postal delivery. For example, CA and not California. Value, by country, is:
- UK. A county.
- US. A state.
- Canada. A province.
- Japan. A prefecture.
- Switzerland. A kanton.
Maximum length: 300.
postal_code

string

The postal code, which is the zip code or equivalent. Typically required for countries with a postal code or an equivalent. See postal code.

Maximum length: 60.
country_code

string

required

The two-character ISO 3166-1 code that identifies the country or region.
Note: The country code for Great Britain is GB and not UK as used in the top-level domain names for that country. Use the C2 country code for China worldwide for comparable uncontrolled price (CUP) method, bank card, and cross-border transactions.

Minimum length: 2.

Maximum length: 2.

Pattern: ^([A-Z]{2}|C2)$.
address_details

object

The non-portable additional address details that are sometimes needed for compliance, risk, or other scenarios where fine-grain address information might be needed. Not portable with common third party and open source. Redundant with core fields.
For example, address_portable.address_line_1 is usually a combination of address_details.street_number, street_name, and street_type.

address_portable_postal_code_validation

address_portable_postal_code_validation

amount_breakdown

item_total

object

The subtotal for all items. Required if the request includes purchase_units[].items[].unit_amount. Must equal the sum of (items[].unit_amount * items[].quantity) for all items.
shipping

object

The shipping fee for all items within a given purchase_unit.
handling

object

The handling fee for all items within a given purchase_unit.
tax_total

object

The total tax for all items. Required if the request includes purchase_units.items.tax. Must equal the sum of (items[].tax * items[].quantity) for all items.
insurance

object

The insurance fee for all items within a given purchase_unit.
shipping_discount

object

The shipping discount for all items within a given purchase_unit.

amount_with_breakdown

currency_code

string

required

The three-character ISO-4217 currency code that identifies the currency.

Minimum length: 3.

Maximum length: 3.
value

string

required
The value, which might be:
- An integer for currencies like JPY that are not typically fractional.
- A decimal fraction for currencies like TND that are subdivided into thousandths.
For the required number of decimal places for a currency code, see Currency Codes.
Maximum length: 32.

Pattern: ^((-?[0-9]+)|(-?([0-9]+)?[.][0-9]+))$.

breakdown

object

The breakdown of the amount. Breakdown provides details such as total item amount, total tax amount, shipping, handling, insurance, and discounts, if any.

application_context

brand_name

string

The label that overrides the business name in the PayPal account on the PayPal site.

Maximum length: 127.
locale

string

The BCP 47-formatted locale of pages that the PayPal payment experience shows. PayPal supports a five-character code. For example, da-DK, he-IL, id-ID, ja-JP, no-NO, pt-BR, ru-RU, sv-SE, th-TH, zh-CN, zh-HK, or zh-TW.

Minimum length: 2.

Maximum length: 10.

Pattern: ^[a-z]{2}(?:-[A-Z][a-z]{3})?(?:-(?:[A-Z]{2}))?$.
landing_page

enum
The type of landing page to show on the PayPal site for customer checkout. The possible values are:
- LOGIN. When the customer clicks PayPal Checkout, the customer is redirected to a page to log in to PayPal and approve the payment.
- BILLING. When the customer clicks PayPal Checkout, the customer is redirected to a page to enter credit or debit card and other relevant billing information required to complete the purchase.
Default: LOGIN.
shipping_preference

enum
The shipping preference:
- Displays the shipping address to the customer.
- Enables the customer to choose an address on the PayPal site.
- Restricts the customer from changing the address during the payment-approval process.
The possible values are:
- GET_FROM_FILE. Use the customer-provided shipping address on the PayPal site.
- NO_SHIPPING. Redact the shipping address from the PayPal site. Recommended for digital goods.
- SET_PROVIDED_ADDRESS. Use the merchant-provided address. The customer cannot change this address on the PayPal site.
Default: GET_FROM_FILE.
user_action

enum
Configures a Continue or Pay Now checkout flow. The possible values are:
- CONTINUE. After you redirect the customer to the PayPal payment page, a Continue button appears. Use this option when the final amount is not known when the checkout flow is initiated and you want to redirect the customer to the merchant page without processing the payment.
- PAY_NOW. After you redirect the customer to the PayPal payment page, a Pay Now button appears. Use this option when the final amount is known when the checkout is initiated and you want to process the payment immediately when the customer clicks Pay Now.
Default: CONTINUE.
payment_method

object

The customer and merchant payment preferences.
return_url

string

The URL where the customer is redirected after the customer approves the payment.
cancel_url

string

The URL where the customer is redirected after the customer cancels the payment.

authorization

status

enum
The status for the authorized payment. The possible values are:
- CREATED. The authorized payment is created. No captured payments have been made for this authorized payment.
- CAPTURED. The authorized payment has one or more captures against it. The sum of these captured payments is greater than the amount of the original authorized payment.
- DENIED. PayPal cannot authorize funds for this authorized payment.
- EXPIRED. The authorized payment has expired.
- PARTIALLY_CAPTURED. A captured payment was made for the authorized payment for an amount that is less than the amount of the original authorized payment.
- VOIDED. The authorized payment was voided. No more captured payments can be made against this authorized payment.
Read only.

id

string

The PayPal-generated ID for the authorized payment.

Read only.
amount

object

The amount for this authorized payment.

Read only.
invoice_id

string

The API caller-provided external invoice number for this order. Appears in both the payer's transaction history and the emails that the payer receives.

Read only.
seller_protection

object

The level of protection offered as defined by PayPal Seller Protection for Merchants.

Read only.
expiration_time

string

The date and time when the authorized payment expires, in Internet date and time format.

Read only.
links

array (contains the link_description object)

An array of related HATEOAS links.

Read only.

create_time

string

The date and time when the transaction occurred, in Internet date and time format.

Read only.

Minimum length: 20.

Maximum length: 64.

Pattern: ^[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})$.
update_time

string

The date and time when the transaction was last updated, in Internet date and time format.

Read only.

Minimum length: 20.

Maximum length: 64.

Pattern: ^[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})$.

authorization_status

status

enum
The status for the authorized payment. The possible values are:
- CREATED. The authorized payment is created. No captured payments have been made for this authorized payment.
- CAPTURED. The authorized payment has one or more captures against it. The sum of these captured payments is greater than the amount of the original authorized payment.
- DENIED. PayPal cannot authorize funds for this authorized payment.
- EXPIRED. The authorized payment has expired.
- PARTIALLY_CAPTURED. A captured payment was made for the authorized payment for an amount that is less than the amount of the original authorized payment.
- VOIDED. The authorized payment was voided. No more captured payments can be made against this authorized payment.
Read only.

authorize_request

payment_source

object

The source of payment for the order, which can be a token or a card. Use this object only if you have not redirected the user after order creation to approve the payment. In such cases, the user-selected payment method in the PayPal flow is implicitly used.

capture

status

enum
The status of the captured payment. The possible values are:
- COMPLETED. The funds for this captured payment were credited to the payee's PayPal account.
- DECLINED. The funds could not be captured.
- PARTIALLY_REFUNDED. An amount less than this captured payment's amount was partially refunded to the payer.
- PENDING. The funds for this captured payment was not yet credited to the payee's PayPal account. For more information, see status.details
- REFUNDED. An amount greater than or equal to this captured payment's amount was refunded to the payer.
Read only.
status_details

object

The details of the captured payment status.

Read only.

id

string

The PayPal-generated ID for the captured payment.

Read only.
amount

object

The amount for this captured payment.

Read only.
invoice_id

string

The API caller-provided external invoice number for this order. Appears in both the payer's transaction history and the emails that the payer receives.

Read only.
seller_protection

object

The level of protection offered as defined by PayPal Seller Protection for Merchants.

Read only.
final_capture

boolean

Indicates whether you can make additional captures against the authorized payment. Set to true if you do not intend to capture additional payments against the authorization. Set to false if you intend to capture additional payments against the authorization.

Read only.
seller_receivable_breakdown

object

The detailed breakdown of the captured payment.

Read only.
disbursement_mode

enum
The funds that are held on behalf of the merchant. The possible values are:
- INSTANT. The funds are released to the merchant immediately.
- DELAYED. The funds are held for a finite number of days. The actual duration depends on the region and type of integration. You can release the funds through a referenced payout. Otherwise, the funds disbursed automatically after the specified duration.
links

array (contains the link_description object)

An array of related HATEOAS links.

Read only.

create_time

string

The date and time when the transaction occurred, in Internet date and time format.

Read only.

Minimum length: 20.

Maximum length: 64.

Pattern: ^[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})$.
update_time

string

The date and time when the transaction was last updated, in Internet date and time format.

Read only.

Minimum length: 20.

Maximum length: 64.

Pattern: ^[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})$.

capture_status

status

enum
The status of the captured payment. The possible values are:
- COMPLETED. The funds for this captured payment were credited to the payee's PayPal account.
- DECLINED. The funds could not be captured.
- PARTIALLY_REFUNDED. An amount less than this captured payment's amount was partially refunded to the payer.
- PENDING. The funds for this captured payment was not yet credited to the payee's PayPal account. For more information, see status.details
- REFUNDED. An amount greater than or equal to this captured payment's amount was refunded to the payer.
Read only.
status_details

object

The details of the captured payment status.

Read only.

capture_status_details

reason

enum
The reason why the captured payment status is PENDING or DENIED. The possible values are:
- BUYER_COMPLAINT. The payer initiated a dispute for this captured payment with PayPal.
- CHARGEBACK. The captured funds were reversed in response to the payer disputing this captured payment with the issuer of the financial instrument used to pay for this captured payment.
- ECHECK. The payer paid by an eCheck that has not yet cleared.
- INTERNATIONAL_WITHDRAWAL. Visit your online account. In your **Account Overview**, accept and deny this payment.
- OTHER. No additional specific reason can be provided. For more information about this captured payment, visit your account online or contact PayPal.
- PENDING_REVIEW. The captured payment is pending manual review.
- RECEIVING_PREFERENCE_MANDATES_MANUAL_ACTION. The payee has not yet set up appropriate receiving preferences for their account. For more information about how to accept or deny this payment, visit your account online. This reason is typically offered in scenarios such as when the currency of the captured payment is different from the primary holding currency of the payee.
- REFUNDED. The captured funds were refunded.
- TRANSACTION_APPROVED_AWAITING_FUNDING. The payer must send the funds for this captured payment. This code generally appears for manual EFTs.
- UNILATERAL. The payee does not have a PayPal account.
- VERIFICATION_REQUIRED. The payee's PayPal account is not verified.

card

id

string

The PayPal-generated ID for the card.

Read only.
name

string

The card holder's name as it appears on the card.

Maximum length: 300.
number

string

required

The primary account number (PAN) for the payment card.

Minimum length: 13.

Maximum length: 19.
expiry

string

required

The card expiration year and month, in Internet date format.

Minimum length: 7.

Maximum length: 7.

Pattern: ^[0-9]{4}-(0[1-9]|1[0-2])$.
security_code

string

The three- or four-digit security code of the card. Also known as the CVV, CVC, CVN, CVE, or CID.

Pattern: [0-9]{3,4}.
last_digits

string

The last digits of the payment card.

Read only.

Pattern: [0-9]{2,}.
card_type

enum
The card brand or network. Typically used in the response. The possible values are:
- VISA. Visa card.
- MASTERCARD. MasterCard card.
- DISCOVER. Discover card.
- AMEX. American Express card.
- SOLO. Solo debit card.
- JCB. Japan Credit Bureau card.
- STAR. Military Star card.
- DELTA. Delta Airlines card.
- SWITCH. Switch credit card.
- MAESTRO. Maestro credit card.
- CB_NATIONALE. Carte Bancaire (CB) credit card.
- CONFIGOGA. Configoga credit card.
- CONFIDIS. Confidis credit card.
- ELECTRON. Visa Electron credit card.
- CETELEM. Cetelem credit card.
- CHINA_UNION_PAY. China union pay credit card.
Read only.

Minimum length: 1.

Maximum length: 255.

Pattern: ^[A-Z_]+$.
billing_address

object

The billing address for this card. Supports only the address_line_1, address_line_2, admin_area_1, admin_area_2, postal_code, and country_code properties.

card_type

card_type

enum
The card network or brand. Applies to credit, debit, gift, and payment cards. The possible values are:
- VISA. Visa card.
- MASTERCARD. MasterCard card.
- DISCOVER. Discover card.
- AMEX. American Express card.
- SOLO. Solo debit card.
- JCB. Japan Credit Bureau card.
- STAR. Military Star card.
- DELTA. Delta Airlines card.
- SWITCH. Switch credit card.
- MAESTRO. Maestro credit card.
- CB_NATIONALE. Carte Bancaire (CB) credit card.
- CONFIGOGA. Configoga credit card.
- CONFIDIS. Confidis credit card.
- ELECTRON. Visa Electron credit card.
- CETELEM. Cetelem credit card.
- CHINA_UNION_PAY. China union pay credit card.
Minimum length: 1.

Maximum length: 255.

Pattern: ^[A-Z_]+$.

checkout_payment_intent

checkout_payment_intent

enum
The intent to either capture payment immediately or authorize a payment for an order after order creation. The possible values are:
- CAPTURE. The merchant intends to capture payment immediately after the customer makes a payment.
- AUTHORIZE. The merchant intends to authorize a payment and place funds on hold after the customer makes a payment. Authorized payments are guaranteed for up to three days but are available to capture for up to 29 days. After the three-day honor period, the original authorized payment expires and you must re-authorize the payment. You must make a separate request to capture payments on demand.

country_code

country_code

string

The two-character ISO 3166-1 code that identifies the country or region.
Note: The country code for Great Britain is GB and not UK as used in the top-level domain names for that country. Use the C2 country code for China worldwide for comparable uncontrolled price (CUP) method, bank card, and cross-border transactions.

Minimum length: 2.

Maximum length: 2.

Pattern: ^([A-Z]{2}|C2)$.

currency_code

currency_code

string

The three-character ISO-4217 currency code that identifies the currency.

Minimum length: 3.

Maximum length: 3.

date_no_time

date_no_time

string

The stand-alone date, in Internet date and time format. To represent special legal values, such as a date of birth, you should use dates with no associated time or time-zone data. Whenever possible, use the standard date_time type. This regular expression does not validate all dates. For example, February 31 is valid and nothing is known about leap years.

Minimum length: 10.

Maximum length: 10.

Pattern: ^[0-9]{4}-(0[1-9]|1[0-2])-(0[1-9]|[1-2][0-9]|3[0-1])$.

date_time

date_time

string

The date and time, in Internet date and time format. Seconds are required while fractional seconds are optional.
Note: The regular expression provides guidance but does not reject all invalid dates.

Minimum length: 20.

Maximum length: 64.

Pattern: ^[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})$.

date_year_month

date_year_month

string

The year and month, in ISO-8601 YYYY-MM date format. See Internet date and time format.

Minimum length: 7.

Maximum length: 7.

Pattern: ^[0-9]{4}-(0[1-9]|1[0-2])$.

disbursement_mode

disbursement_mode

enum
The funds that are held on behalf of the merchant. The possible values are:
- INSTANT. The funds are released to the merchant immediately.
- DELAYED. The funds are held for a finite number of days. The actual duration depends on the region and type of integration. You can release the funds through a referenced payout. Otherwise, the funds disbursed automatically after the specified duration.
Default: INSTANT.

dispute_category

dispute_category

enum
The condition that is covered for the transaction. The possible values are:
- ITEM_NOT_RECEIVED. The payer paid for an item that he or she did not receive.
- UNAUTHORIZED_TRANSACTION. The payer did not authorize the payment.

email

email

string

The internationalized email address.
Note: Up to 64 characters are allowed before and 255 characters are allowed after the @ sign. However, the generally accepted maximum length for an email address is 254 characters. The pattern verifies that an unquoted @ sign exists.

Maximum length: 254.

Pattern: (?:[a-zA-Z0-9!#$%&'*+/=?^_`{|}~-]+(?:\.[a-zA-Z0-9!#$%&'*+/=?^_`{|}~-]+)*|(?:[\x01-\x08\x0b\x0c\x0e-\x1f\x21\x23-\x5b\x5d-\x7f]|\[\x01-\x09\x0b\x0c\x0e-\x7f])*")@(?:(?:[a-zA-Z0-9](?:[a-zA-Z0-9-]*[a-zA-Z0-9])?\.)+[a-zA-Z0-9](?:[a-zA-Z0-9-]*[a-zA-Z0-9])?|\[(?:(?:(2(5[0-5]|[0-4][0-9])|1[0-9][0-9]|[1-9]?[0-9]))\.){3}(?:(2(5[0-5]|[0-4][0-9])|1[0-9][0-9]|[1-9]?[0-9])|[a-zA-Z0-9-]*[a-zA-Z0-9]:(?:[\x01-\x08\x0b\x0c\x0e-\x1f\x21-\x5a\x53-\x7f]|\[\x01-\x09\x0b\x0c\x0e-\x7f])+)\]).

error

name

string

required

The human-readable, unique name of the error.
message

string

required

The message that describes the error.
debug_id

string

required

The PayPal internal ID. Used for correlation purposes.
information_link

string

The information link, or URI, that shows detailed information about this error for the developer.

Read only.
details

array (contains the error_details object)

An array of additional details about the error.
links

array (contains the link_description object)

An array of request-related HATEOAS links.

Read only.

error_details

field

string

The field that caused the error. If this field is in the body, set this value to the field's JSON pointer value. Required for client-side errors.
value

string

The value of the field that caused the error.
location

string

The location of the field that caused the error. Value is body, path, or query.

Default: body.
issue

string

required

The unique, fine-grained application-level error code.
description

string

The human-readable description for an issue. The description can change over the lifetime of an API, so clients must not depend on this value.

exchange_rate

source_currency

string

The source currency from which to convert an amount.

Read only.
target_currency

string

The target currency into which to convert an amount.

Read only.
value

string

The target currency amount. Equivalent to one unit of the source currency. Formatted as integer or decimal value with one to 15 digits to the right of the decimal point.

Read only.

item

name

string

required

The item name or title.

Minimum length: 1.

Maximum length: 127.
unit_amount

object

required

The item price or rate per unit. If you specify unit_amount, purchase_units[].amount.breakdown.item_total is required. Must equal unit_amount * quantity for all items.
tax

object

The item tax for each unit. If tax is specified, purchase_units[].amount.breakdown.tax_total is required. Must equal tax * quantity for all items.
quantity

string

required

The item quantity. Must be a whole number.

Maximum length: 10.

Pattern: ^[1-9][0-9]{0,9}$.
description

string

The detailed item description.

Maximum length: 127.
sku

string

The stock keeping unit (SKU) for the item.

Maximum length: 127.
category

enum
The item category type. The possible values are:
- DIGITAL_GOODS. Goods that are stored, delivered, and used in their electronic format.
- PHYSICAL_GOODS. A tangible item that can be shipped with proof of delivery.
Minimum length: 1.

Maximum length: 20.

language

language

string

The language tag for the language in which to localize the error-related strings, such as messages, issues, and suggested actions. The tag is made up of the ISO 639-2 language code, the optional ISO-15924 script tag, and the ISO-3166 alpha-2 country code.

Minimum length: 2.

Maximum length: 10.

Pattern: ^[a-z]{2}(?:-[A-Z][a-z]{3})?(?:-(?:[A-Z]{2}))?$.

link_description

href

string

required

The complete target URL. To make the related call, combine the method with this URI Template-formatted link. For pre-processing, include the $, (, and ) characters. The href is the key HATEOAS component that links a completed call with a subsequent call.
rel

string

required

The link relation type, which serves as an ID for a link that unambiguously describes the semantics of the link. See Link Relations.
method

enum

The HTTP method required to make the related call.

Possible values: GET, POST, PUT, DELETE, HEAD, CONNECT, OPTIONS, PATCH.

money

currency_code

string

required

The three-character ISO-4217 currency code that identifies the currency.

Minimum length: 3.

Maximum length: 3.
value

string

required
The value, which might be:
- An integer for currencies like JPY that are not typically fractional.
- A decimal fraction for currencies like TND that are subdivided into thousandths.
For the required number of decimal places for a currency code, see Currency Codes.
Maximum length: 32.

Pattern: ^((-?[0-9]+)|(-?([0-9]+)?[.][0-9]+))$.

name

prefix

string

The prefix, or title, to the party's name.

Maximum length: 140.
given_name

string

When the party is a person, the party's given, or first, name.

Maximum length: 140.
surname

string

When the party is a person, the party's surname or family name. Also known as the last name. Required when the party is a person. Use also to store multiple surnames including the matronymic, or mother's, surname.

Maximum length: 140.
middle_name

string

When the party is a person, the party's middle name. Use also to store multiple middle names including the patronymic, or father's, middle name.

Maximum length: 140.
suffix

string

The suffix for the party's name.

Maximum length: 140.
alternate_full_name

string

DEPRECATED. The party's alternate name. Can be a business name, nickname, or any other name that cannot be split into first, last name. Required when the party is a business.

Maximum length: 300.
full_name

string

When the party is a person, the party's full name.

Maximum length: 300.

name

full_name

string

When the party is a person, the party's full name.

Maximum length: 300.

name

given_name

string

When the party is a person, the party's given, or first, name.

Maximum length: 140.
surname

string

When the party is a person, the party's surname or family name. Also known as the last name. Required when the party is a person. Use also to store multiple surnames including the matronymic, or mother's, surname.

Maximum length: 140.

name_validation

name_validation

net_amount_breakdown_item

payable_amount

object

The net amount debited from the merchant's PayPal account.

Read only.
converted_amount

object

The converted payable amount.

Read only.
exchange_rate

object

The exchange rate that determines the amount that was debited from the merchant's PayPal account.

Read only.

order

create_time

string

The date and time when the transaction occurred, in Internet date and time format.

Read only.

Minimum length: 20.

Maximum length: 64.

Pattern: ^[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})$.
update_time

string

The date and time when the transaction was last updated, in Internet date and time format.

Read only.

Minimum length: 20.

Maximum length: 64.

Pattern: ^[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})$.

id

string

The ID of the order.

Read only.
intent

enum
The intent to either capture payment immediately or authorize a payment for an order after order creation. The possible values are:
- CAPTURE. The merchant intends to capture payment immediately after the customer makes a payment.
- AUTHORIZE. The merchant intends to authorize a payment and place funds on hold after the customer makes a payment. Authorized payments are guaranteed for up to three days but are available to capture for up to 29 days. After the three-day honor period, the original authorized payment expires and you must re-authorize the payment. You must make a separate request to capture payments on demand.
payer

object

The customer who approves and pays for the order. The customer is also known as the payer.
purchase_units

array (contains the purchase_unit object)

An array of purchase units. Each purchase unit establishes a contract between a customer and merchant. Each purchase unit represents either a full or partial order that the customer intends to purchase from the merchant.
status

enum
The order status. The possible values are:
- CREATED. The order was created with the specified context.
- SAVED. The order was saved and persisted. The order status continues to be in progress until a capture is made with final_capture = true for all purchase units within the order.
- APPROVED. The customer approved the payment through the PayPal wallet or another form of guest or unbranded payment. For example, a card, bank account, or so on.
- VOIDED. All purchase units in the order are voided.
- COMPLETED. The payment was authorized or the authorized payment was captured for the order.
Read only.
links

array (contains the link_description object)

An array of request-related HATEOAS links. To complete payer approval, use the approve link with the GET method.

Read only.

order_action_request

payment_source

object

The source of payment for the order, which can be a token or a card. Use this object only if you have not redirected the user after order creation to approve the payment. In such cases, the user-selected payment method in the PayPal flow is implicitly used.

order_capture_request

payment_source

object

The payment source definition.

order_request

intent

enum

required
The intent to either capture payment immediately or authorize a payment for an order after order creation. The possible values are:
- CAPTURE. The merchant intends to capture payment immediately after the customer makes a payment.
- AUTHORIZE. The merchant intends to authorize a payment and place funds on hold after the customer makes a payment. Authorized payments are guaranteed for up to three days but are available to capture for up to 29 days. After the three-day honor period, the original authorized payment expires and you must re-authorize the payment. You must make a separate request to capture payments on demand.
payer

object

The customer who approves and pays for the order. The customer is also known as the payer.
purchase_units

array (contains the purchase_unit_request object)

required

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

object

Customize the payer experience during the approval process for the payment with PayPal.

order_status

order_status

enum
The order status. The possible values are:
- CREATED. The order was created with the specified context.
- SAVED. The order was saved and persisted. The order status continues to be in progress until a capture is made with final_capture = true for all purchase units within the order.
- APPROVED. The customer approved the payment through the PayPal wallet or another form of guest or unbranded payment. For example, a card, bank account, or so on.
- VOIDED. All purchase units in the order are voided.
- COMPLETED. The payment was authorized or the authorized payment was captured for the order.

patch

`op`

enum

required

The operation. The possible values are:

add. Depending on the target location reference, completes one of these functions:
- The target location is an array index. Inserts a new value into the array at the specified index.
- The target location is an object parameter that does not already exist. Adds a new parameter to the object.
- The target location is an object parameter that does exist. Replaces that parameter's value.
The value parameter defines the value to add. For more information, see 4.1. add.
remove. Removes the value at the target location. For the operation to succeed, the target location must exist. For more information, see 4.2. remove.
replace. Replaces the value at the target location with a new value. The operation object must contain a value parameter that defines the replacement value. For the operation to succeed, the target location must exist. For more information, see 4.3. replace.
move. Removes the value at a specified location and adds it to the target location. The operation object must contain a from parameter, which is a string that contains a JSON pointer value that references the location in the target document from which to move the value. For the operation to succeed, the from location must exist. For more information, see 4.4. move.
copy. Copies the value at a specified location to the target location. The operation object must contain a from parameter, which is a string that contains a JSON pointer value that references the location in the target document from which to copy the value. For the operation to succeed, the from location must exist. For more information, see 4.5. copy.

test. Tests that a value at the target location is equal to a specified value. The operation object must contain a value parameter that defines the value to compare to the target location's value. For the operation to succeed, the target location must be equal to the value value. For test, equal indicates that the value at the target location and the value that value defines are of the same JSON type. The data type of the value determines how equality is defined:

Type	Considered equal if both values
strings	Contain the same number of Unicode characters and their code points are byte-by-byte equal.
numbers	Are numerically equal.
arrays	Contain the same number of values, and each value is equal to the value at the corresponding position in the other array, by using these type-specific rules.
objects	Contain the same number of parameters, and each parameter is equal to a parameter in the other object, by comparing their keys (as strings) and their values (by using these type-specific rules).
literals (`false`, `true`, and `null`)	Are the same. The comparison is a logical comparison. For example, whitespace between the parameter values of an array is not significant. Also, ordering of the serialization of object parameters is not significant.

For more information, see 4.6. test.

path

string

The JSON Pointer to the target document location at which to complete the operation.
value

number,integer,string,boolean,null,array,object

The value to apply. The remove operation does not require a value.
from

string

The JSON Pointer to the target document location from which to move the value. Required for the move operation.

patch_request

patch_request

array (contains the patch object)

An array of JSON patch objects to apply partial updates to resources.

payee

email_address

string

The email address of merchant.
merchant_id

string

The encrypted PayPal account ID of the merchant.

payee_base

email_address

string

The email address of merchant.
merchant_id

string

The encrypted PayPal account ID of the merchant.

payer

name

object

The name of the payer. Supports only the given_name and surname properties.
email_address

string

The email address of the payer.

Maximum length: 254.

Pattern: (?:[a-zA-Z0-9!#$%&'*+/=?^_`{|}~-]+(?:\.[a-zA-Z0-9!#$%&'*+/=?^_`{|}~-]+)*|(?:[\x01-\x08\x0b\x0c\x0e-\x1f\x21\x23-\x5b\x5d-\x7f]|\[\x01-\x09\x0b\x0c\x0e-\x7f])*")@(?:(?:[a-zA-Z0-9](?:[a-zA-Z0-9-]*[a-zA-Z0-9])?\.)+[a-zA-Z0-9](?:[a-zA-Z0-9-]*[a-zA-Z0-9])?|\[(?:(?:(2(5[0-5]|[0-4][0-9])|1[0-9][0-9]|[1-9]?[0-9]))\.){3}(?:(2(5[0-5]|[0-4][0-9])|1[0-9][0-9]|[1-9]?[0-9])|[a-zA-Z0-9-]*[a-zA-Z0-9]:(?:[\x01-\x08\x0b\x0c\x0e-\x1f\x21-\x5a\x53-\x7f]|\[\x01-\x09\x0b\x0c\x0e-\x7f])+)\]).
payer_id

string

The PayPal assigned ID for the payer.

Read only.

Minimum length: 13.

Maximum length: 13.

Pattern: ^[2-9A-HJ-NP-Z]{13}$.
phone

object

The phone number of the customer. Available only when you enable the Contact Telephone Number option in the Profile & Settings for the merchant's PayPal account. The phone.phone_number supports only national_number.
birth_date

string

The birth date of the payer in YYYY-MM-DD format.

Minimum length: 10.

Maximum length: 10.

Pattern: ^[0-9]{4}-(0[1-9]|1[0-2])-(0[1-9]|[1-2][0-9]|3[0-1])$.
tax_info

object

The tax information of the payer. Required only for Brazilian payer's. Both tax_id and tax_id_type are required.
address

object

The address of the payer. Supports only the address_line_1, address_line_2, admin_area_1, admin_area_2, postal_code, and country_code properties. Also referred to as the billing address of the customer.

payer_id

payer_id

string

The PayPal payer ID, which is a masked version of the PayPal account number intended for use with third parties. The account number is reversibly encrypted and a proprietary variant of Base32 is used to encode the result.

Minimum length: 13.

Maximum length: 13.

Pattern: ^[2-9A-HJ-NP-Z]{13}$.

payment_collection

authorizations

array (contains the authorization object)

An array of authorized payments for a purchase unit. A purchase unit can have zero or more authorized payments.
captures

array (contains the capture object)

An array of captured payments for a purchase unit. A purchase unit can have zero or more captured payments.
refunds

array (contains the refund object)

An array of refunds for a purchase unit. A purchase unit can have zero or more refunds.

payment_instruction

platform_fees

array (contains the platform_fee object)

An array of various fees, commissions, tips, or donations.
disbursement_mode

enum
The funds that are held on behalf of the merchant. The possible values are:
- INSTANT. The funds are released to the merchant immediately.
- DELAYED. The funds are held for a finite number of days. The actual duration depends on the region and type of integration. You can release the funds through a referenced payout. Otherwise, the funds disbursed automatically after the specified duration.
Default: INSTANT.

payment_method

payer_selected

enum
The customer-selected payment method on the merchant site. The possible values are:
- PAYPAL_CREDIT. When payer chooses PayPal Credit as the payment method.
- PAYPAL. When payer chooses PayPal as the payment method
Default: PAYPAL.

Minimum length: 1.

Pattern: ^[0-9A-Z_]+$.
payee_preferred

enum
The merchant-preferred payment sources. The possible values are:
- UNRESTRICTED. Accepts any type of payment from the customer.
- IMMEDIATE_PAYMENT_REQUIRED. Accepts only immediate payment from the customer. For example, credit card, PayPal balance, or instant ACH. Ensures that at the time of capture, the payment does not have the `pending` status.
Default: UNRESTRICTED.

Minimum length: 1.

Pattern: ^[0-9A-Z_]+$.

payment_source

card

object

The payment card to use to fund a payment. Can be a credit or debit card.
token

object

The tokenized payment source to fund a payment.

phone

national_number

string

required

The national number, in its canonical international E.164 numbering plan format. The combined length of the country calling code (CC) and the national number must not be greater than 15 digits. The national number consists of a national destination code (NDC) and subscriber number (SN).

Minimum length: 1.

Maximum length: 14.

Pattern: ^[0-9]{1,14}?$.

phone

country_code

string

required

The country calling code (CC), in its canonical international E.164 numbering plan format. The combined length of the CC and the national number must not be greater than 15 digits. The national number consists of a national destination code (NDC) and subscriber number (SN).

Minimum length: 1.

Maximum length: 3.

Pattern: ^[0-9]{1,3}?$.
national_number

string

required

The national number, in its canonical international E.164 numbering plan format. The combined length of the country calling code (CC) and the national number must not be greater than 15 digits. The national number consists of a national destination code (NDC) and subscriber number (SN).

Minimum length: 1.

Maximum length: 14.

Pattern: ^[0-9]{1,14}?$.
extension_number

string

The extension number.

Minimum length: 1.

Maximum length: 15.

Pattern: ^[0-9]{1,15}?$.

phone_type

phone_type

enum

The phone type.

Possible values: FAX, HOME, MOBILE, OTHER, PAGER.

phone_with_type

phone_type

enum

The phone type.

Possible values: FAX, HOME, MOBILE, OTHER, PAGER.
phone_number

object

required

The phone number, in its canonical international E.164 numbering plan format. Supports only the national_number property.

platform_fee

amount

object

required

The fee for this transaction.
payee

object

The recipient of the fee for this transaction. If you omit this value, the default is the API caller.

purchase_unit

reference_id

string

The API caller-provided external ID for the purchase unit. Required for multiple purchase units when you must update the order through PATCH. If not provided and there is only 1 purchase_unit as part of the order, value is automatically set by PayPal to default.

Maximum length: 256.
amount

object

The total order amount with an optional breakdown that provides details, such as the total item amount, total tax amount, shipping, handling, insurance, and discounts, if any.
If you specify amount.breakdown, the amount equals item_total plus tax_total plus shipping plus handling plus insurance minus shipping_discount.
The amount must be a positive number. For listed of supported currencies and decimal precision, see the PayPal REST APIs Currency Codes.
payee

object

The merchant who receives payment for this transaction.
payment_instruction

object

Any additional payment instructions for PayPal for Partner customers. Enables features for partners and marketplaces, such as delayed disbursement and collection of a platform fee. Applies during order creation for captured payments or during capture of authorized payments.
description

string

The purchase description.

Maximum length: 127.
custom_id

string

The API caller-provided external ID. Used to reconcile API caller-initiated transactions with PayPal transactions. Appears in transaction and settlement reports.

Maximum length: 127.
invoice_id

string

The API caller-provided external invoice ID for this order.

Maximum length: 127.
id

string

The PayPal-generated ID for the purchase unit. This ID appears in both the payer's transaction history and the emails that the payer receives. In addition, this ID is available in transaction and settlement reports that merchants and API callers can use to reconcile transactions. This ID is only available when an order is saved by calling v2/checkout/orders/id/save.

Maximum length: 19.
soft_descriptor

string

The payment descriptor on the customer's credit card statement of account transactions.

Maximum length: 22.
items

array (contains the item object)

An array of items that the customer purchases from the merchant.
shipping

object

The shipping address and method.
payments

object

The comprehensive history of payments for the purchase unit.

Read only.

purchase_unit_request

reference_id

string

The ID for the purchase unit. Required for multiple purchase_units or if an order must be updated by using PATCH. If you omit the reference_id for an order with one purchase unit, PayPal sets the reference_id to default.

Maximum length: 256.
amount

object

required

The total order amount with an optional breakdown that provides details, such as the total item amount, total tax amount, shipping, handling, insurance, and discounts, if any.
If you specify amount.breakdown, the amount equals item_total plus tax_total plus shipping plus handling plus insurance minus shipping_discount.
The amount must be a positive number. For listed of supported currencies and decimal precision, see the PayPal REST APIs Currency Codes.
payee

object

The merchant who receives payment for this transaction.
payment_instruction

object

Any additional payment instructions for PayPal for Partner customers. Enables features for partners and marketplaces, such as delayed disbursement and collection of a platform fee. Applies during order creation for captured payments or during capture of authorized payments.
description

string

The purchase description.

Maximum length: 127.
custom_id

string

The API caller-provided external ID. Used to reconcile client transactions with PayPal transactions. Appears in transaction and settlement reports but is not visible to the payer.

Maximum length: 127.
invoice_id

string

The API caller-provided external invoice number for this order. Appears in both the payer's transaction history and the emails that the payer receives.

Maximum length: 127.
soft_descriptor

string

The payment descriptor on the payer's credit card statement.

Maximum length: 22.
items

array (contains the item object)

An array of items that the customer is purchasing from the merchant.
shipping

object

The name and address of the person to whom to ship the items.

refund

status

enum
The status of the capture. The possible values are:
- CANCELLED. The refund was cancelled.
- PENDING. The refund is pending. For more information, see status_details.reason.
- COMPLETED. The funds for this transaction were debited to the customer's account.
Read only.
status_details

object

The details of the refund status.

Read only.

id

string

The PayPal-generated ID for the refund.

Read only.
amount

object

The amount that the payee refunded to the payer.

Read only.
invoice_id

string

The API caller-provided external invoice number for this order. Appears in both the payer's transaction history and the emails that the payer receives.

Read only.
note_to_payer

string

The reason for the refund. Appears in both the payer's transaction history and the emails that the payer receives.

Read only.
seller_payable_breakdown

object

The breakdown of the refund.

Read only.
links

array (contains the link_description object)

An array of related HATEOAS links.

Read only.

create_time

string

The date and time when the transaction occurred, in Internet date and time format.

Read only.

Minimum length: 20.

Maximum length: 64.

Pattern: ^[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})$.
update_time

string

The date and time when the transaction was last updated, in Internet date and time format.

Read only.

Minimum length: 20.

Maximum length: 64.

Pattern: ^[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})$.

refund_status

status

enum
The status of the capture. The possible values are:
- CANCELLED. The refund was cancelled.
- PENDING. The refund is pending. For more information, see status_details.reason.
- COMPLETED. The funds for this transaction were debited to the customer's account.
Read only.
status_details

object

The details of the refund status.

Read only.

refund_status_details

reason

enum
The reason why the refund has the PENDING or FAILED status. The possible values are:
- ECHECK. The customer's account is funded through an eCheck, which has not yet cleared.

seller_payable_breakdown

gross_amount

object

The amount that the payee refunded to the payer.

Read only.
paypal_fee

object

The PayPal fee that was refunded to the payer. This fee might not match the PayPal fee that the payee paid when the payment was captured.

Read only.
net_amount

object

The net amount that the payee's account is debited, if the payee holds funds in the currency for this refund. The net amount is calculated as gross_amount minus paypal_fee minus platform_fees.

Read only.
platform_fees

array (contains the platform_fee object)

An array of platform or partner fees, commissions, or brokerage fees for the refund.

Read only.
net_amount_breakdown

array (contains the net_amount_breakdown_item object)

An array of breakdown values for the net amount. Returned when the currency of the refund is different from the currency of the PayPal account where the payee holds their funds.

Read only.
total_refunded_amount

object

The total amount refunded from the original capture to date. For example, if a payer makes a $100 purchase and was refunded $20 a week ago and was refunded $30 in this refund, the gross_amount is $30 for this refund and the total_refunded_amount is $50.

Read only.

seller_protection

status

enum
Indicates whether the transaction is eligible for seller protection. For information, see PayPal Seller Protection for Merchants. The possible values are:
- ELIGIBLE. Your PayPal balance remains intact if the customer claims that he or she did not receive an item or the account holder claims that he or she did not authorize the payment.
- PARTIALLY_ELIGIBLE. Your PayPal balance remains intact if the customer claims that he or she did not receive an item.
- NOT_ELIGIBLE. This transaction is not eligible for seller protection.
Read only.
dispute_categories

array (contains the dispute_category object)

An array of conditions that are covered for the transaction.

Read only.

seller_receivable_breakdown

gross_amount

object

The amount for this captured payment.

Read only.
paypal_fee

object

The applicable fee for this captured payment.

Read only.
net_amount

object

The net amount that the payee receives for this captured payment in their PayPal account. The net amount is computed as gross_amount minus the paypal_fee minus the platform_fees.

Read only.
receivable_amount

object

The net amount that is credited to the payee's PayPal account. Returned only when the currency of the captured payment is different from the currency of the PayPal account where the payee wants to credit the funds. The amount is computed as net_amount times exchange_rate.

Read only.
exchange_rate

object

The exchange rate that determines the amount that is credited to the payee's PayPal account. Returned when the currency of the captured payment is different from the currency of the PayPal account where the payee wants to credit the funds.

Read only.
platform_fees

array (contains the platform_fee object)

An array of platform or partner fees, commissions, or brokerage fees that associated with the captured payment.

Read only.

shipping_detail

name

object

The name of the person to whom to ship the items. Supports only the full_name property.
address

object

The address of the person to whom to ship the items. Supports only the address_line_1, address_line_2, admin_area_1, admin_area_2, postal_code, and country_code properties.

tax_info

tax_id

string

required

The customer's tax ID. Supported for the PayPal payment method only. Typically, the tax ID is 11 characters long for individuals and 14 characters long for businesses.

Maximum length: 14.
tax_id_type

enum

required
The customer's tax ID type. Supported for the PayPal payment method only. The possible values are:
- BR_CPF. The individual tax ID type.
- BR_CNPJ. The business tax ID type.

token

id

string

required

The PayPal-generated ID for the token.

Minimum length: 1.

Maximum length: 255.
type

enum

required
The tokenization method that was used to generate the ID. The possible values are:
- NONCE. A secure, one-time-use reference to a payment source, such as payment card, PayPal account, and so on.
- PAYMENT_METHOD_TOKEN. The payment method token, which is a reference to a transactional payment source. Typically stored on the merchant's server.
- BILLING_AGREEMENT. The PayPal billing agreement ID. References an approved recurring payment for goods or services.
Minimum length: 1.

Maximum length: 255.

Pattern: ^[0-9A-Z_-]+$.

Error messages

In addition to common HTTP status codes that the REST APIs return, the Orders API can return the following errors.

ACTION_DOES_NOT_MATCH_INTENT

Order was created with an intent to CAPTURE.
To complete the transaction, call capture payment for order or create an order with an intent of AUTHORIZE.
AGREEMENT_ALREADY_CANCELLED

The requested agreement is already cancelled.
The specified agreement ID cannot be used for this transaction.
AMOUNT_MISMATCH

The amount specified does not match the breakdown.
The amount must equal item_total + tax_total + shipping + handling + insurance - shipping_discount.
AMOUNT_NOT_PATCHABLE

The requested action could not be completed, was semantically incorrect, or failed business validation.
The amount cannot be updated as the 'payer' has chosen and approved a specific financing offer for a given amount. Please Create a new Order with the updated Order amount and have the 'payer' approve the new payment terms.
AUTHENTICATION_FAILURE

Authentication failed due to missing authorization header, or invalid authentication credentials.
Account validations failed for the user.
BILLING_AGREEMENT_NOT_FOUND

The requested Billing Agreement token was not found.
Verify the token and try the request again.
CANNOT_BE_NEGATIVE

Must be greater than or equal to zero.
Try the request again with a different value.
CANNOT_BE_ZERO_OR_NEGATIVE

Must be greater than zero.
Try the request again with a different value.
CARD_TYPE_NOT_SUPPORTED

The requested action could not be completed, was semantically incorrect, or failed business validation.
Processing of this card type is not supported. Use another type of card.
CITY_REQUIRED

The specified country requires a city (address.admin_area_2).
Specify a city and try the request again.
COMPLIANCE_VIOLATION

Transaction cannot be processed due to a possible compliance violation.
To get more information about the transaction, call customer support.
CONSENT_NEEDED

Authorization failed due to insufficient permissions.
To continue with this transaction, payer consent is required.
DECIMAL_PRECISION

The value of the field should not be more than two decimal places.
Verify the number of decimal places and try the request again.
DOMESTIC_TRANSACTION_REQUIRED

This transaction requires the payee and payer to be resident in the same country.
To create this payment, a domestic transaction is required.
DUPLICATE_INVOICE_ID

Duplicate Invoice ID detected.
To avoid a duplicate transaction, verify that the invoice ID is unique for each transaction.
DUPLICATE_REQUEST_ID

The value of PayPal-Request-Id header has already been used.
Try a different value and try the request again.
FIELD_NOT_PATCHABLE

Field cannot be patched.
You cannot patch this field.
INSTRUMENT_DECLINED

The funding instrument presented was either declined by the processor or bank.
The specified funding instrument cannot be used for this payment.
INTERNAL_SERVER_ERROR

An internal server error has occurred.
Retry the request later.
INVALID_ACCOUNT_STATUS

Account validations failed for the user.
To continue with this transaction, payer consent is required.
INVALID_ARRAY_MAX_ITEMS

The number of items in an array parameter is too large.
The number of items in an array parameter is too large.
INVALID_ARRAY_MIN_ITEMS

The number of items in an array parameter is too small.
The number of items in an array parameter is too small.
INVALID_COUNTRY_CODE

Country code is invalid.
For list of supported country codes, see Country and Region Codes.
INVALID_CURRENCY_CODE

Currency code is invalid or is not currently supported.
For a list of supported currency codes, see Currency Codes.
INVALID_JSON_POINTER_FORMAT

Path should be a valid JavaScript Object Notation (JSON) Pointer that references a location within the request where the operation is performed.
The path is not valid.
INVALID_PARAMETER

Cannot be specified as part of the request.
Check that the API supports this parameter and try the request again.
INVALID_PARAMETER_SYNTAX

The value of a field does not conform to the expected format.
Verify that the pattern is supported and try the request again.
INVALID_PARAMETER_VALUE

The value of a field is invalid.
Verify the parameter value and try the request again.
INVALID_PAYER_ID

The payer ID is not valid.
Verify the payer ID and try the request again.
INVALID_RESOURCE_ID

Specified resource ID does not exist.
Verify the resource ID and try the request again.
INVALID_STRING_LENGTH

The value of a field is either too short or too long.
Verify the minimum and maximum values and try the request again.
ITEM_TOTAL_MISMATCH

Verify the corresponding values and try the request again.
Should equal sum of (unit_amount * quantity) across all items for a given purchase_unit.
ITEM_TOTAL_REQUIRED

If item details are specified (items.unit_amount and items.quantity) corresponding amount.breakdown.item_total is required.
The amount.breakdown.item_total value was not found.
MAX_NUMBER_OF_PAYMENT_ATTEMPTS_EXCEEDED

You have exceeded the maximum number of payment attempts.
To review the maximum number of payment attempts allowed and retry this transaction, call customer support.
MAX_VALUE_EXCEEDED

Should be less than or equal to 9999999.99.
Try the request again with a different value.
MISSING_REQUIRED_PARAMETER

A required field or parameter is missing.
Verify that you have specified all required parameters and try the request again.
MISSING_SHIPPING_ADDRESS

The shipping address is required when shipping_preference=SET_PROVIDED_ADDRESS.
Verify that you have provided the shipping address and try the request again.
MULTI_CURRENCY_ORDER

Multiple differing values of currency_code are not supported.
The entire order request must have the same currency code.
MULTIPLE_SHIPPING_ADDRESS_NOT_SUPPORTED

Multiple shipping addresses are not supported.
Try the request again with the same shipping_address.
NOT_AUTHORIZED

Authorization failed due to insufficient permissions.
To check that your application has sufficient permissions, log in to the PayPal Developer Portal.
NOT_PATCHABLE

Cannot be patched.
You cannot patch this field.
NOT_SUPPORTED

This field is not currently supported.
Specify only supported parameters and try the request again.
ORDER_NOT_APPROVED

Payer has not yet approved the Order for payment.
The payer has not yet approved payment for the order. Redirect the payer to the rel:approve URL that was returned in the HATEOAS links in the create order response or provide a valid payment_source in the request.
ORDER_ALREADY_AUTHORIZED

Order already authorized. If 'intent=AUTHORIZE' only one authorization per order is allowed.
The order was already authorized and you can create one authorization for an order.
ORDER_ALREADY_CAPTURED

Order already captured. If 'intent=CAPTURE' only one capture per order is allowed.
The order was already captured and you can capture only one payment for an order.
PARAMETER_VALUE_NOT_SUPPORTED

The value specified for this field is not currently supported.
The specified parameter value is not supported.
PATCH_VALUE_REQUIRED

Please specify a 'value' to for the field that is being patched.
Try your request again.
PATCH_PATH_REQUIRED

Specify a path for the field for which the operation needs to be performed.
To complete the operation for this field, specify a path for the field.
PAYEE_ACCOUNT_INVALID

Mismatch between request payeeId and payeeEmail.
Specify either payee.merchant_id or payee.email_address.
PAYEE_ACCOUNT_LOCKED_OR_CLOSED

Payee account is locked or closed.
To get more information about the status of the account, call customer support.
PAYEE_ACCOUNT_RESTRICTED

The merchant account is restricted.
To get more information about the status of the account, call customer support.
PAYEE_BLOCKED_TRANSACTION

The fraud settings for this seller are such that this payment cannot be executed.
Verify the fraud settings. Then, retry the transaction.
PAYER_ACCOUNT_LOCKED_OR_CLOSED

Payer account is locked or closed.
To get more information about the status of the account, call customer support.
PAYER_ACCOUNT_RESTRICTED

Payer account is restricted.
To get more information about the status of the account, call customer support.
PAYER_CANNOT_PAY

The combination of payer and payee settings mean that this payer can't pay this payee.
Verify the settings and try the request again.
PAYER_CONSENT_REQUIRED

The payer has not provided appropriate consent to proceed with this transaction.
To proceed with the transaction, you must get payer consent.
PAYMENT_INSTRUCTION_REQUIRED

You must provide the payment instruction when you capture an authorized payment for intent=AUTHORIZE.
For details, see Capture authorization. For intent=CAPTURE, send the payment instruction when you create the order.
PERMISSION_DENIED

You do not have permission to access or perform operations on this resource.
If you are make API calls on behalf of a merchant or payee, ensure that you have been granted appropriate permissions to continue with this request.
POSTAL_CODE_REQUIRED

The specified country requires a postal code.
Specify a postal code and try the request again.
REDIRECT_PAYER_FOR_ALTERNATE_FUNDING

Transaction failed. Redirect the payer to select another funding source.
The transaction failed. Redirect the payer to select another funding source.
REFERENCE_ID_NOT_FOUND

Filter expression value is incorrect.
Check the value of the reference_id and try the request again.
TAX_TOTAL_MISMATCH

Should equal sum of (tax * quantity) across all items for a given purchase_unit.
The tax total must equal the sum of (tax * quantity) across all items for a purchase_unit.
TAX_TOTAL_REQUIRED

If item details are specified (items.tax_total and items.quantity), the corresponding amount.breakdown.tax_total is required.
The amount.breakdown.tax_total is a required field.
TRANSACTION_AMOUNT_EXCEEDS_MONTHLY_MAX_LIMIT

The transaction amount exceeds monthly maximum limit.
To review the monthly transaction limits and retry this transaction, call customer support.
TRANSACTION_LIMIT_EXCEEDED

Total payment amount exceeded transaction limit.
To review the transaction limit and retry this transaction, call customer support.
TRANSACTION_RECEIVING_LIMIT_EXCEEDED

The transaction exceeds the payee's receiving limit.
To review the transaction limit and retry this transaction, call customer support.
TRANSACTION_REFUSED

The transaction was refused.
Verify the transaction and try the request again.
UNSUPPORTED_PATCH_PARAMETER_VALUE

The value specified for this field is not currently supported.
Try the request again with a different value.
UNSUPPORTED_PAYMENT_INSTRUCTION

Only supported when the intent=CAPTURE.
If intent is AUTHORIZE, you must provide a payment_instruction when you capture payment for the authorization. For details, see capture authorized payment.

PayPal-Partner-Attribution-Id

Prefer

Authorization

Content-Type

intent

payer

purchase_units

application_context

Sample Request

create_time

update_time

id

intent

payer

purchase_units

status

links

Sample Response

Authorization

Content-Type

order_id

patch_request

Sample Request

Sample Response

Authorization

Content-Type

order_id

Sample Request

create_time

update_time

id

intent

payer

purchase_units

status

links

Sample Response

PayPal-Request-Id

Prefer

PayPal-Client-Metadata-Id

Authorization

PayPal-Auth-Assertion

Content-Type

order_id

payment_source

Sample Request

create_time

update_time

id

intent

payer

purchase_units

status

links

Sample Response

PayPal-Request-Id

Prefer

PayPal-Client-Metadata-Id

Authorization

PayPal-Auth-Assertion

Content-Type

order_id

payment_source

Sample Request

create_time

update_time

id

intent

payer

purchase_units

status

links

Sample Response

create_time

update_time

street_number

street_name

street_type

delivery_service

building_name

`PayPal-Partner-Attribution-Id`

`Prefer`

`Authorization`

`Content-Type`

`intent`

`payer`

`purchase_units`

`application_context`

`create_time`

`update_time`

`id`

`intent`

`payer`

`purchase_units`

`status`

`links`

`Authorization`

`Content-Type`

`order_id`

`patch_request`

`Authorization`

`Content-Type`

`order_id`

`create_time`

`update_time`

`id`

`intent`

`payer`

`purchase_units`

`status`

`links`

`PayPal-Request-Id`

`Prefer`

`PayPal-Client-Metadata-Id`

`Authorization`

`PayPal-Auth-Assertion`

`Content-Type`

`order_id`

`payment_source`

`create_time`

`update_time`

`id`

`intent`

`payer`

`purchase_units`

`status`

`links`

`PayPal-Request-Id`

`Prefer`

`PayPal-Client-Metadata-Id`

`Authorization`

`PayPal-Auth-Assertion`

`Content-Type`

`order_id`

`payment_source`

`create_time`

`update_time`

`id`

`intent`

`payer`

`purchase_units`

`status`

`links`

`create_time`

`update_time`

`street_number`

`street_name`

`street_type`

`delivery_service`

`building_name`

`sub_building`

`address_line_1`

`address_line_2`

`admin_area_2`

`admin_area_1`

`postal_code`

`country_code`

`address_line_1`

`address_line_2`

`admin_area_2`