Orders (2)

API Version v2

An order represents a payment between two or more parties. Use the Orders API to create, update, retrieve, authorize, and capture orders.

Create order

post/v2/checkout/orders

Creates an order. Merchants and partners can add Level 2 and 3 data to payments to reduce risk and payment processing costs. For more information about processing payments, see checkout or multiparty checkout.

Note: For error handling and troubleshooting, see Orders v2 errors.

SecurityOauth2
Request
header Parameters
PayPal-Request-Id
string [ 1 .. 36 ] characters

The server stores keys for 6 hours. The API callers can request the times to up to 72 hours by speaking to their Account Manager.

PayPal-Partner-Attribution-Id
string [ 1 .. 36 ] characters
PayPal-Client-Metadata-Id
string [ 1 .. 36 ] characters
Prefer
string [ 1 .. 25 ] characters ^[a-zA-Z=]*$
Default: return=minimal

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.

Authorization
required
string

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
required
string [ 1 .. 255 ] characters ^[A-Za-z0-9/+-]+$

The media type. Required for operations with a request body. The value is application/<format>, where format is json.

Request Body schema: application/json
required
Array of objects (Purchase Unit Request) [ 1 .. 10 ] items

An array of purchase units. 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.

intent
required
string (checkout_payment_intent)

The intent to either capture payment immediately or authorize a payment for an order after order creation.

Enum: Description
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 best captured within three days of authorization 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. This intent is not supported when you have more than one purchase_unit within your order.

object <payer_v1> (payer)

DEPRECATED. The customer is also known as the payer. The Payer object was intended to only be used with the payment_source.paypal object. In order to make this design more clear, the details in the payer object are now available under payment_source.paypal. Please use payment_source.paypal.

object (payment_source)

The payment source definition.

object (application_context)

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

Responses
200

A successful response to an idempotent request returns the HTTP 200 OK status code with a JSON response body that shows order details.

Request samples
application/json
{
  • "purchase_units": [
    • {
      • "reference_id": "d9f80740-38f0-11e8-b467-0ed5f89f718b",
      • "description": "string",
      • "custom_id": "string",
      • "invoice_id": "string",
      • "soft_descriptor": "string",
      • "items": [
        • {
          • "name": "string",
          • "quantity": "string",
          • "description": "string",
          • "sku": "string",
          • "category": "DIGITAL_GOODS",
          • "unit_amount": {
            • "currency_code": "str",
            • "value": "string"
            },
          • "tax": {
            • "currency_code": "str",
            • "value": "string"
            }
          }
        ],
      • "amount": {
        • "currency_code": "USD",
        • "value": "100.00",
        • "breakdown": {
          • "item_total": {
            • "currency_code": "str",
            • "value": "string"
            },
          • "shipping": {
            • "currency_code": "str",
            • "value": "string"
            },
          • "handling": {
            • "currency_code": "str",
            • "value": "string"
            },
          • "tax_total": {
            • "currency_code": "str",
            • "value": "string"
            },
          • "insurance": {
            • "currency_code": "str",
            • "value": "string"
            },
          • "shipping_discount": {
            • "currency_code": "str",
            • "value": "string"
            },
          • "discount": {
            • "currency_code": "str",
            • "value": "string"
            }
          }
        },
      • "payee": {
        • "email_address": "string",
        • "merchant_id": "stringstrings"
        },
      • "payment_instruction": {
        • "platform_fees": [
          • {
            • "amount": {
              • "currency_code": "str",
              • "value": "string"
              },
            • "payee": {
              • "email_address": "string",
              • "merchant_id": "stringstrings"
              }
            }
          ],
        • "payee_pricing_tier_id": "string",
        • "payee_receivable_fx_rate_id": "string",
        • "disbursement_mode": "INSTANT"
        },
      • "shipping": {
        • "type": "SHIPPING",
        • "name": {
          • "given_name": "string",
          • "surname": "string"
          },
        • "address": {
          • "address_line_1": "string",
          • "address_line_2": "string",
          • "admin_area_2": "string",
          • "admin_area_1": "string",
          • "postal_code": "string",
          • "country_code": "st"
          }
        },
      • "supplementary_data": {
        • "card": {
          • "level_2": {
            • "invoice_id": "string",
            • "tax_total": {
              • "currency_code": "str",
              • "value": "string"
              }
            },
          • "level_3": {
            • "ships_from_postal_code": "string",
            • "line_items": [
              • {
                • "name": null,
                • "quantity": null,
                • "description": null,
                • "sku": null,
                • "category": null,
                • "unit_amount": null,
                • "tax": null,
                • "commodity_code": null,
                • "unit_of_measure": null,
                • "discount_amount": null,
                • "total_amount": null
                }
              ],
            • "shipping_amount": {
              • "currency_code": "str",
              • "value": "string"
              },
            • "duty_amount": {
              • "currency_code": "str",
              • "value": "string"
              },
            • "discount_amount": {
              • "currency_code": "str",
              • "value": "string"
              },
            • "shipping_address": {
              • "address_line_1": "string",
              • "address_line_2": "string",
              • "admin_area_2": "string",
              • "admin_area_1": "string",
              • "postal_code": "string",
              • "country_code": "st"
              }
            }
          }
        }
      }
    ],
  • "intent": "CAPTURE",
  • "payer": {
    • "email_address": "string",
    • "name": {
      • "given_name": "string",
      • "surname": "string"
      },
    • "phone": {
      • "phone_type": "FAX",
      • "phone_number": {
        • "national_number": "string"
        }
      },
    • "birth_date": "stringstri",
    • "tax_info": {
      • "tax_id": "string",
      • "tax_id_type": "BR_CPF"
      },
    • "address": {
      • "address_line_1": "string",
      • "address_line_2": "string",
      • "admin_area_2": "string",
      • "admin_area_1": "string",
      • "postal_code": "string",
      • "country_code": "st"
      }
    },
  • "payment_source": {
    • "card": {
      • "name": "string",
      • "number": "stringstrings",
      • "security_code": "stri",
      • "expiry": "string",
      • "billing_address": {
        • "address_line_1": "string",
        • "address_line_2": "string",
        • "admin_area_2": "string",
        • "admin_area_1": "string",
        • "postal_code": "string",
        • "country_code": "st"
        },
      • "attributes": {
        • "customer": {
          • "id": "string",
          • "email_address": "string",
          • "phone": {
            • "phone_type": "FAX",
            • "phone_number": {
              • "national_number": "string"
              }
            }
          },
        • "vault": {
          • "store_in_vault": "ON_SUCCESS"
          }
        },
      • "stored_credential": {
        • "payment_initiator": "CUSTOMER",
        • "payment_type": "ONE_TIME",
        • "usage": "FIRST",
        • "previous_network_transaction_reference": {
          • "id": "stringstr",
          • "date": "stri",
          • "network": "VISA"
          }
        },
      • "vault_id": "string"
      },
    • "token": {
      • "id": "string",
      • "type": "BILLING_AGREEMENT"
      },
    • "paypal": {
      • "experience_context": {
        • "brand_name": "EXAMPLE INC",
        • "shipping_preference": "SET_PROVIDED_ADDRESS",
        • "landing_page": "LOGIN",
        • "user_action": "PAY_NOW",
        • "payment_method_preference": "IMMEDIATE_PAYMENT_REQUIRED",
        • "locale": "en-US",
        • "return_url": "https://example.com/returnUrl",
        • "cancel_url": "https://example.com/cancelUrl",
        • "payment_method_selected": "PAYPAL"
        },
      • "billing_agreement_id": "string",
      • "vault_id": "string",
      • "email_address": "string",
      • "name": {
        • "given_name": "string",
        • "surname": "string"
        },
      • "phone": {
        • "phone_type": "FAX",
        • "phone_number": {
          • "national_number": "string"
          }
        },
      • "birth_date": "stringstri",
      • "tax_info": {
        • "tax_id": "string",
        • "tax_id_type": "BR_CPF"
        },
      • "address": {
        • "address_line_1": "string",
        • "address_line_2": "string",
        • "admin_area_2": "string",
        • "admin_area_1": "string",
        • "postal_code": "string",
        • "country_code": "st"
        },
      • "attributes": {
        • "customer": {
          • "id": "string"
          },
        • "vault": {
          • "store_in_vault": "ON_SUCCESS",
          • "description": "string",
          • "usage_pattern": "string",
          • "usage_type": "string",
          • "customer_type": "CONSUMER",
          • "permit_multiple_payment_tokens": false
          }
        }
      },
    • "bancontact": {
      • "name": "string",
      • "country_code": "string",
      • "experience_context": {
        • "brand_name": "string",
        • "shipping_preference": "GET_FROM_FILE",
        • "locale": "string",
        • "return_url": "string",
        • "cancel_url": "string"
        }
      },
    • "blik": {
      • "name": "string",
      • "country_code": "string",
      • "email": "string",
      • "experience_context": {
        • "brand_name": "string",
        • "shipping_preference": "GET_FROM_FILE",
        • "locale": "string",
        • "return_url": "string",
        • "cancel_url": "string"
        }
      },
    • "eps": {
      • "name": "string",
      • "country_code": "string",
      • "experience_context": {
        • "brand_name": "string",
        • "shipping_preference": "GET_FROM_FILE",
        • "locale": "string",
        • "return_url": "string",
        • "cancel_url": "string"
        }
      },
    • "giropay": {
      • "name": "string",
      • "country_code": "string",
      • "experience_context": {
        • "brand_name": "string",
        • "shipping_preference": "GET_FROM_FILE",
        • "locale": "string",
        • "return_url": "string",
        • "cancel_url": "string"
        }
      },
    • "ideal": {
      • "name": "string",
      • "country_code": "string",
      • "bic": "string",
      • "experience_context": {
        • "brand_name": "string",
        • "shipping_preference": "GET_FROM_FILE",
        • "locale": "string",
        • "return_url": "string",
        • "cancel_url": "string"
        }
      },
    • "mybank": {
      • "name": "string",
      • "country_code": "string",
      • "experience_context": {
        • "brand_name": "string",
        • "shipping_preference": "GET_FROM_FILE",
        • "locale": "string",
        • "return_url": "string",
        • "cancel_url": "string"
        }
      },
    • "p24": {
      • "name": "string",
      • "email": "string",
      • "country_code": "string",
      • "experience_context": {
        • "brand_name": "string",
        • "shipping_preference": "GET_FROM_FILE",
        • "locale": "string",
        • "return_url": "string",
        • "cancel_url": "string"
        }
      },
    • "sofort": {
      • "name": "string",
      • "country_code": "string",
      • "experience_context": {
        • "brand_name": "string",
        • "shipping_preference": "GET_FROM_FILE",
        • "locale": "string",
        • "return_url": "string",
        • "cancel_url": "string"
        }
      },
    • "trustly": {
      • "name": "string",
      • "country_code": "string",
      • "experience_context": {
        • "brand_name": "string",
        • "shipping_preference": "GET_FROM_FILE",
        • "locale": "string",
        • "return_url": "string",
        • "cancel_url": "string"
        }
      },
    • "venmo": {
      • "experience_context": {
        • "brand_name": "string",
        • "shipping_preference": "GET_FROM_FILE"
        },
      • "vault_id": "string",
      • "email_address": "string",
      • "attributes": {
        • "customer": {
          • "id": "string"
          },
        • "vault": {
          • "store_in_vault": "ON_SUCCESS",
          • "description": "string",
          • "usage_pattern": "string",
          • "usage_type": "string",
          • "customer_type": "CONSUMER",
          • "permit_multiple_payment_tokens": false
          }
        }
      }
    },
  • "application_context": {
    • "brand_name": "string",
    • "landing_page": "LOGIN",
    • "shipping_preference": "GET_FROM_FILE",
    • "user_action": "CONTINUE",
    • "return_url": "http://example.com",
    • "cancel_url": "http://example.com",
    • "locale": "string",
    • "payment_method": {
      • "standard_entry_class_code": "TEL",
      • "payee_preferred": "UNRESTRICTED"
      },
    • "stored_payment_source": {
      • "payment_initiator": "CUSTOMER",
      • "payment_type": "ONE_TIME",
      • "usage": "FIRST",
      • "previous_network_transaction_reference": {
        • "id": "stringstr",
        • "date": "stri",
        • "network": "VISA"
        }
      }
    }
}
Response samples
application/json
{}

Show order details

get/v2/checkout/orders/{id}

Shows details for an order, by ID.

Note: For error handling and troubleshooting, see Orders v2 errors.

SecurityOauth2
Request
path Parameters
id
required
string [ 1 .. 36 ] characters ^[A-Z0-9]+$

The ID of the order for which to show details.

query Parameters
fields
string^[a-z_]*$

A comma-separated list of fields that should be returned for the order. Valid filter field is payment_source.

header Parameters
Authorization
required
string

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
required
string [ 1 .. 255 ] characters ^[A-Za-z0-9/+-]+$

The media type. Required for operations with a request body. The value is application/<format>, where format is json.

Responses
200

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

Request samples 
curl -v -X GET https://api-m.sandbox.paypal.com/v2/checkout/orders/5O190127TN364715T \
-H 'Authorization: Bearer access_token6V7rbVwmlM1gFZKW_8QtzWXqpcwQ6T5vhEGYNJDAAdn3paCgRpdeMdVYmWzgbKSsECednupJ3Zx5Xd-g'
Response samples
application/json
{}

Update order

patch/v2/checkout/orders/{id}

Updates an order with a 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 this value with an order that contains only one purchase unit, PayPal sets the value to default which enables you to use the path: "/purchase_units/@reference_id=='default'/{attribute-or-object}". Merchants and partners can add Level 2 and 3 data to payments to reduce risk and payment processing costs. For more information about processing payments, see checkout or multiparty checkout.

Note: For error handling and troubleshooting, see <a href="/api/rest/reference/orders/v2/errors/#patch-order">Orders v2 errors.
Patchable attributes or objects:

AttributeOpNotes
intentreplace
payerreplace, addUsing replace op for payer will replace the whole payer object with the value sent in request.
purchase_unitsreplace, add
purchase_units[].custom_idreplace, add, remove
purchase_units[].descriptionreplace, add, remove
purchase_units[].payee.emailreplace
purchase_units[].shipping.namereplace, add
purchase_units[].shipping.addressreplace, add
purchase_units[].shipping.typereplace, add
purchase_units[].soft_descriptorreplace, remove
purchase_units[].amountreplace
purchase_units[].invoice_idreplace, add, remove
purchase_units[].payment_instructionreplace
purchase_units[].payment_instruction.disbursement_modereplaceBy default, disbursement_mode is INSTANT.
purchase_units[].payment_instruction.platform_feesreplace, add, remove
purchase_units[].supplementary_data.cardreplace, add, remove
application_context.client_configurationreplace, add

SecurityOauth2
Request
path Parameters
id
required
string [ 1 .. 36 ] characters ^[A-Z0-9]+$

The ID of the order to update.

header Parameters
Authorization
required
string

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
required
string [ 1 .. 255 ] characters ^[A-Za-z0-9/+-]+$

The media type. Required for operations with a request body. The value is application/<format>, where format is json.

Request Body schema: application/json
Array
op
required
string

The operation.

Enum: Description
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:

TypeConsidered equal if both values
stringsContain the same number of Unicode characters and their code points are byte-by-byte equal.
numbersAre numerically equal.
arraysContain 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.
objectsContain 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
object (Patch Value)

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.

Responses
204

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

Request samples
application/json
[
  • {
    • "op": "replace",
    • "path": "/purchase_units/@reference_id=='PUHF'/shipping/address",
    • "value": {
      • "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"
      }
    }
]

Confirm the Order

post/v2/checkout/orders/{id}/confirm-payment-source

Payer confirms their intent to pay for the the Order with the given payment source.

SecurityOauth2
Request
path Parameters
id
required
string [ 1 .. 36 ] characters ^[A-Z0-9]+$

The ID of the order for which the payer confirms their intent to pay.

header Parameters
PayPal-Client-Metadata-Id
string [ 1 .. 36 ] characters
Authorization
required
string

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
required
string [ 1 .. 255 ] characters ^[A-Za-z0-9/+-]+$

The media type. Required for operations with a request body. The value is application/<format>, where format is json.

Prefer
string [ 1 .. 25 ] characters ^[a-zA-Z=]*$
Default: return=minimal

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.

Request Body schema: application/json
processing_instruction
string (Processing Instruction) [ 1 .. 36 ] characters ^[0-9A-Z_]+$
Default: "NO_INSTRUCTION"

The instruction to process an order.

Enum: Description
ORDER_COMPLETE_ON_PAYMENT_APPROVAL

API Caller expects the Order to be auto completed (i.e. for PayPal to authorize or capture depending on the intent) on completion of payer approval. This option is not relevant for payment_source that typically do not require a payer approval or interaction. This option is currently only available for the following payment_source: Alipay, Bancontact, BLIK, boletobancario, eps, giropay, GrabPay, iDEAL, Multibanco, MyBank, OXXO, P24, PayU, PUI, SafetyPay, SatisPay, Sofort, Trustly, Verkkopankki, WeChat Pay

NO_INSTRUCTION

The API caller intends to authorize v2/checkout/orders/id/authorize or capture v2/checkout/orders/id/capture after the payer approves the order.

object (Confirm Application Context)

Customizes the payer confirmation experience.

required
object (payment_source)

The payment source definition.

Responses
200

A successful request indicates that the payment source was added to the Order. A successful request returns the HTTP 200 OK status code with a JSON response body that shows order details.

Request samples
application/json
{
  • "processing_instruction": "ORDER_COMPLETE_ON_PAYMENT_APPROVAL",
  • "application_context": {
    • "brand_name": "string",
    • "return_url": "http://example.com",
    • "cancel_url": "http://example.com",
    • "locale": "string",
    • "stored_payment_source": {
      • "payment_initiator": "CUSTOMER",
      • "payment_type": "ONE_TIME",
      • "usage": "FIRST",
      • "previous_network_transaction_reference": {
        • "id": "stringstr",
        • "date": "stri",
        • "network": "VISA"
        }
      }
    },
  • "payment_source": {
    • "card": {
      • "name": "string",
      • "number": "stringstrings",
      • "security_code": "stri",
      • "expiry": "string",
      • "billing_address": {
        • "address_line_1": "string",
        • "address_line_2": "string",
        • "admin_area_2": "string",
        • "admin_area_1": "string",
        • "postal_code": "string",
        • "country_code": "st"
        },
      • "attributes": {
        • "customer": {
          • "id": "string",
          • "email_address": "string",
          • "phone": {
            • "phone_type": "FAX",
            • "phone_number": {
              • "national_number": "string"
              }
            }
          },
        • "vault": {
          • "store_in_vault": "ON_SUCCESS"
          }
        },
      • "stored_credential": {
        • "payment_initiator": "CUSTOMER",
        • "payment_type": "ONE_TIME",
        • "usage": "FIRST",
        • "previous_network_transaction_reference": {
          • "id": "stringstr",
          • "date": "stri",
          • "network": "VISA"
          }
        },
      • "vault_id": "string"
      },
    • "token": {
      • "id": "string",
      • "type": "BILLING_AGREEMENT"
      },
    • "paypal": {
      • "experience_context": {
        • "brand_name": "EXAMPLE INC",
        • "shipping_preference": "SET_PROVIDED_ADDRESS",
        • "landing_page": "LOGIN",
        • "user_action": "PAY_NOW",
        • "payment_method_preference": "IMMEDIATE_PAYMENT_REQUIRED",
        • "locale": "en-US",
        • "return_url": "https://example.com/returnUrl",
        • "cancel_url": "https://example.com/cancelUrl",
        • "payment_method_selected": "PAYPAL"
        },
      • "billing_agreement_id": "string",
      • "vault_id": "string",
      • "email_address": "customer@example.com",
      • "name": {
        • "given_name": "John",
        • "surname": "Doe"
        },
      • "phone": {
        • "phone_type": "FAX",
        • "phone_number": {
          • "national_number": "string"
          }
        },
      • "birth_date": "stringstri",
      • "tax_info": {
        • "tax_id": "string",
        • "tax_id_type": "BR_CPF"
        },
      • "address": {
        • "address_line_1": "string",
        • "address_line_2": "string",
        • "admin_area_2": "string",
        • "admin_area_1": "string",
        • "postal_code": "string",
        • "country_code": "st"
        },
      • "attributes": {
        • "customer": {
          • "id": "string"
          },
        • "vault": {
          • "store_in_vault": "ON_SUCCESS",
          • "description": "string",
          • "usage_pattern": "string",
          • "usage_type": "string",
          • "customer_type": "CONSUMER",
          • "permit_multiple_payment_tokens": false
          }
        }
      },
    • "bancontact": {
      • "name": "string",
      • "country_code": "string",
      • "experience_context": {
        • "brand_name": "string",
        • "shipping_preference": "GET_FROM_FILE",
        • "locale": "string",
        • "return_url": "string",
        • "cancel_url": "string"
        }
      },
    • "blik": {
      • "name": "string",
      • "country_code": "string",
      • "email": "string",
      • "experience_context": {
        • "brand_name": "string",
        • "shipping_preference": "GET_FROM_FILE",
        • "locale": "string",
        • "return_url": "string",
        • "cancel_url": "string"
        }
      },
    • "eps": {
      • "name": "string",
      • "country_code": "string",
      • "experience_context": {
        • "brand_name": "string",
        • "shipping_preference": "GET_FROM_FILE",
        • "locale": "string",
        • "return_url": "string",
        • "cancel_url": "string"
        }
      },
    • "giropay": {
      • "name": "string",
      • "country_code": "string",
      • "experience_context": {
        • "brand_name": "string",
        • "shipping_preference": "GET_FROM_FILE",
        • "locale": "string",
        • "return_url": "string",
        • "cancel_url": "string"
        }
      },
    • "ideal": {
      • "name": "string",
      • "country_code": "string",
      • "bic": "string",
      • "experience_context": {
        • "brand_name": "string",
        • "shipping_preference": "GET_FROM_FILE",
        • "locale": "string",
        • "return_url": "string",
        • "cancel_url": "string"
        }
      },
    • "mybank": {
      • "name": "string",
      • "country_code": "string",
      • "experience_context": {
        • "brand_name": "string",
        • "shipping_preference": "GET_FROM_FILE",
        • "locale": "string",
        • "return_url": "string",
        • "cancel_url": "string"
        }
      },
    • "p24": {
      • "name": "string",
      • "email": "string",
      • "country_code": "string",
      • "experience_context": {
        • "brand_name": "string",
        • "shipping_preference": "GET_FROM_FILE",
        • "locale": "string",
        • "return_url": "string",
        • "cancel_url": "string"
        }
      },
    • "sofort": {
      • "name": "string",
      • "country_code": "string",
      • "experience_context": {
        • "brand_name": "string",
        • "shipping_preference": "GET_FROM_FILE",
        • "locale": "string",
        • "return_url": "string",
        • "cancel_url": "string"
        }
      },
    • "trustly": {
      • "name": "string",
      • "country_code": "string",
      • "experience_context": {
        • "brand_name": "string",
        • "shipping_preference": "GET_FROM_FILE",
        • "locale": "string",
        • "return_url": "string",
        • "cancel_url": "string"
        }
      },
    • "venmo": {
      • "experience_context": {
        • "brand_name": "string",
        • "shipping_preference": "GET_FROM_FILE"
        },
      • "vault_id": "string",
      • "email_address": "string",
      • "attributes": {
        • "customer": {
          • "id": "string"
          },
        • "vault": {
          • "store_in_vault": "ON_SUCCESS",
          • "description": "string",
          • "usage_pattern": "string",
          • "usage_type": "string",
          • "customer_type": "CONSUMER",
          • "permit_multiple_payment_tokens": false
          }
        }
      }
    }
}
Response samples
application/json
{}

Authorize payment for order

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

Authorizes payment for an order. To successfully authorize payment for an order, the buyer must first approve the order or a valid payment_source must be provided in the request. A buyer can approve the order upon being redirected to the rel:approve URL that was returned in the HATEOAS links in the create order response.

Note: For error handling and troubleshooting, see Orders v2 errors.

SecurityOauth2
Request
path Parameters
id
required
string [ 1 .. 36 ] characters ^[A-Z0-9]+$

The ID of the order for which to authorize.

header Parameters
PayPal-Request-Id
string [ 1 .. 36 ] characters

The server stores keys for 6 hours. The API callers can request the times to up to 72 hours by speaking to their Account Manager.

Prefer
string [ 1 .. 25 ] characters ^[a-zA-Z=]*$
Default: return=minimal

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.

PayPal-Client-Metadata-Id
string [ 1 .. 36 ] characters
Authorization
required
string

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
required
string [ 1 .. 255 ] characters ^[A-Za-z0-9/+-]+$

The media type. Required for operations with a request body. The value is application/<format>, where format is json.

Request Body schema: application/json
object (payment_source)

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.

Responses
201

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.

Request samples
application/json
{
  • "payment_source": {
    • "card": {
      • "name": "string",
      • "number": "stringstrings",
      • "security_code": "stri",
      • "expiry": "string",
      • "billing_address": {
        • "address_line_1": "string",
        • "address_line_2": "string",
        • "admin_area_2": "string",
        • "admin_area_1": "string",
        • "postal_code": "string",
        • "country_code": "st"
        },
      • "attributes": {
        • "customer": {
          • "id": "string",
          • "email_address": "string",
          • "phone": {
            • "phone_type": "FAX",
            • "phone_number": {
              • "national_number": "string"
              }
            }
          },
        • "vault": {
          • "store_in_vault": "ON_SUCCESS"
          }
        },
      • "stored_credential": {
        • "payment_initiator": "CUSTOMER",
        • "payment_type": "ONE_TIME",
        • "usage": "FIRST",
        • "previous_network_transaction_reference": {
          • "id": "stringstr",
          • "date": "stri",
          • "network": "VISA"
          }
        },
      • "vault_id": "string"
      },
    • "token": {
      • "id": "string",
      • "type": "BILLING_AGREEMENT"
      },
    • "paypal": {
      • "experience_context": {
        • "brand_name": "string",
        • "shipping_preference": "GET_FROM_FILE",
        • "landing_page": "LOGIN",
        • "user_action": "CONTINUE",
        • "payment_method_preference": "UNRESTRICTED",
        • "locale": "string",
        • "return_url": "string",
        • "cancel_url": "string"
        },
      • "billing_agreement_id": "string",
      • "vault_id": "string",
      • "email_address": "string",
      • "name": {
        • "given_name": "string",
        • "surname": "string"
        },
      • "phone": {
        • "phone_type": "FAX",
        • "phone_number": {
          • "national_number": "string"
          }
        },
      • "birth_date": "stringstri",
      • "tax_info": {
        • "tax_id": "string",
        • "tax_id_type": "BR_CPF"
        },
      • "address": {
        • "address_line_1": "string",
        • "address_line_2": "string",
        • "admin_area_2": "string",
        • "admin_area_1": "string",
        • "postal_code": "string",
        • "country_code": "st"
        },
      • "attributes": {
        • "customer": {
          • "id": "string"
          },
        • "vault": {
          • "store_in_vault": "ON_SUCCESS",
          • "description": "string",
          • "usage_pattern": "string",
          • "usage_type": "string",
          • "customer_type": "CONSUMER",
          • "permit_multiple_payment_tokens": false
          }
        }
      },
    • "bancontact": {
      • "name": "string",
      • "country_code": "string",
      • "experience_context": {
        • "brand_name": "string",
        • "shipping_preference": "GET_FROM_FILE",
        • "locale": "string",
        • "return_url": "string",
        • "cancel_url": "string"
        }
      },
    • "blik": {
      • "name": "string",
      • "country_code": "string",
      • "email": "string",
      • "experience_context": {
        • "brand_name": "string",
        • "shipping_preference": "GET_FROM_FILE",
        • "locale": "string",
        • "return_url": "string",
        • "cancel_url": "string"
        }
      },
    • "eps": {
      • "name": "string",
      • "country_code": "string",
      • "experience_context": {
        • "brand_name": "string",
        • "shipping_preference": "GET_FROM_FILE",
        • "locale": "string",
        • "return_url": "string",
        • "cancel_url": "string"
        }
      },
    • "giropay": {
      • "name": "string",
      • "country_code": "string",
      • "experience_context": {
        • "brand_name": "string",
        • "shipping_preference": "GET_FROM_FILE",
        • "locale": "string",
        • "return_url": "string",
        • "cancel_url": "string"
        }
      },
    • "ideal": {
      • "name": "string",
      • "country_code": "string",
      • "bic": "string",
      • "experience_context": {
        • "brand_name": "string",
        • "shipping_preference": "GET_FROM_FILE",
        • "locale": "string",
        • "return_url": "string",
        • "cancel_url": "string"
        }
      },
    • "mybank": {
      • "name": "string",
      • "country_code": "string",
      • "experience_context": {
        • "brand_name": "string",
        • "shipping_preference": "GET_FROM_FILE",
        • "locale": "string",
        • "return_url": "string",
        • "cancel_url": "string"
        }
      },
    • "p24": {
      • "name": "string",
      • "email": "string",
      • "country_code": "string",
      • "experience_context": {
        • "brand_name": "string",
        • "shipping_preference": "GET_FROM_FILE",
        • "locale": "string",
        • "return_url": "string",
        • "cancel_url": "string"
        }
      },
    • "sofort": {
      • "name": "string",
      • "country_code": "string",
      • "experience_context": {
        • "brand_name": "string",
        • "shipping_preference": "GET_FROM_FILE",
        • "locale": "string",
        • "return_url": "string",
        • "cancel_url": "string"
        }
      },
    • "trustly": {
      • "name": "string",
      • "country_code": "string",
      • "experience_context": {
        • "brand_name": "string",
        • "shipping_preference": "GET_FROM_FILE",
        • "locale": "string",
        • "return_url": "string",
        • "cancel_url": "string"
        }
      },
    • "venmo": {
      • "experience_context": {
        • "brand_name": "string",
        • "shipping_preference": "GET_FROM_FILE"
        },
      • "vault_id": "string",
      • "email_address": "string",
      • "attributes": {
        • "customer": {
          • "id": "string"
          },
        • "vault": {
          • "store_in_vault": "ON_SUCCESS",
          • "description": "string",
          • "usage_pattern": "string",
          • "usage_type": "string",
          • "customer_type": "CONSUMER",
          • "permit_multiple_payment_tokens": false
          }
        }
      }
    }
}
Response samples
application/json
{}

Capture payment for order

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

Captures payment for an order. To successfully capture payment for an order, the buyer must first approve the order or a valid payment_source must be provided in the request. A buyer can approve the order upon being redirected to the rel:approve URL that was returned in the HATEOAS links in the create order response.

Note: For error handling and troubleshooting, see Orders v2 errors.

SecurityOauth2
Request
path Parameters
id
required
string [ 1 .. 36 ] characters ^[A-Z0-9]+$

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

header Parameters
PayPal-Request-Id
string [ 1 .. 36 ] characters

The server stores keys for 6 hours. The API callers can request the times to up to 72 hours by speaking to their Account Manager.

Prefer
string [ 1 .. 25 ] characters ^[a-zA-Z=]*$
Default: return=minimal

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.

PayPal-Client-Metadata-Id
string [ 1 .. 36 ] characters
Authorization
required
string

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
required
string [ 1 .. 255 ] characters ^[A-Za-z0-9/+-]+$

The media type. Required for operations with a request body. The value is application/<format>, where format is json.

Request Body schema: application/json
object (payment_source)

The payment source definition.

Responses
201

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.

Request samples
application/json
{
  • "payment_source": {
    • "card": {
      • "name": "string",
      • "number": "stringstrings",
      • "security_code": "stri",
      • "expiry": "string",
      • "billing_address": {
        • "address_line_1": "string",
        • "address_line_2": "string",
        • "admin_area_2": "string",
        • "admin_area_1": "string",
        • "postal_code": "string",
        • "country_code": "st"
        },
      • "attributes": {
        • "customer": {
          • "id": "string",
          • "email_address": "string",
          • "phone": {
            • "phone_type": "FAX",
            • "phone_number": {
              • "national_number": "string"
              }
            }
          },
        • "vault": {
          • "store_in_vault": "ON_SUCCESS"
          }
        },
      • "stored_credential": {
        • "payment_initiator": "CUSTOMER",
        • "payment_type": "ONE_TIME",
        • "usage": "FIRST",
        • "previous_network_transaction_reference": {
          • "id": "stringstr",
          • "date": "stri",
          • "network": "VISA"
          }
        },
      • "vault_id": "string"
      },
    • "token": {
      • "id": "string",
      • "type": "BILLING_AGREEMENT"
      },
    • "paypal": {
      • "experience_context": {
        • "brand_name": "string",
        • "shipping_preference": "GET_FROM_FILE",
        • "landing_page": "LOGIN",
        • "user_action": "CONTINUE",
        • "payment_method_preference": "UNRESTRICTED",
        • "locale": "string",
        • "return_url": "string",
        • "cancel_url": "string"
        },
      • "billing_agreement_id": "string",
      • "vault_id": "string",
      • "email_address": "string",
      • "name": {
        • "given_name": "string",
        • "surname": "string"
        },
      • "phone": {
        • "phone_type": "FAX",
        • "phone_number": {
          • "national_number": "string"
          }
        },
      • "birth_date": "stringstri",
      • "tax_info": {
        • "tax_id": "string",
        • "tax_id_type": "BR_CPF"
        },
      • "address": {
        • "address_line_1": "string",
        • "address_line_2": "string",
        • "admin_area_2": "string",
        • "admin_area_1": "string",
        • "postal_code": "string",
        • "country_code": "st"
        },
      • "attributes": {
        • "customer": {
          • "id": "string"
          },
        • "vault": {
          • "store_in_vault": "ON_SUCCESS",
          • "description": "string",
          • "usage_pattern": "string",
          • "usage_type": "string",
          • "customer_type": "CONSUMER",
          • "permit_multiple_payment_tokens": false
          }
        }
      },
    • "bancontact": {
      • "name": "string",
      • "country_code": "string",
      • "experience_context": {
        • "brand_name": "string",
        • "shipping_preference": "GET_FROM_FILE",
        • "locale": "string",
        • "return_url": "string",
        • "cancel_url": "string"
        }
      },
    • "blik": {
      • "name": "string",
      • "country_code": "string",
      • "email": "string",
      • "experience_context": {
        • "brand_name": "string",
        • "shipping_preference": "GET_FROM_FILE",
        • "locale": "string",
        • "return_url": "string",
        • "cancel_url": "string"
        }
      },
    • "eps": {
      • "name": "string",
      • "country_code": "string",
      • "experience_context": {
        • "brand_name": "string",
        • "shipping_preference": "GET_FROM_FILE",
        • "locale": "string",
        • "return_url": "string",
        • "cancel_url": "string"
        }
      },
    • "giropay": {
      • "name": "string",
      • "country_code": "string",
      • "experience_context": {
        • "brand_name": "string",
        • "shipping_preference": "GET_FROM_FILE",
        • "locale": "string",
        • "return_url": "string",
        • "cancel_url": "string"
        }
      },
    • "ideal": {
      • "name": "string",
      • "country_code": "string",
      • "bic": "string",
      • "experience_context": {
        • "brand_name": "string",
        • "shipping_preference": "GET_FROM_FILE",
        • "locale": "string",
        • "return_url": "string",
        • "cancel_url": "string"
        }
      },
    • "mybank": {
      • "name": "string",
      • "country_code": "string",
      • "experience_context": {
        • "brand_name": "string",
        • "shipping_preference": "GET_FROM_FILE",
        • "locale": "string",
        • "return_url": "string",
        • "cancel_url": "string"
        }
      },
    • "p24": {
      • "name": "string",
      • "email": "string",
      • "country_code": "string",
      • "experience_context": {
        • "brand_name": "string",
        • "shipping_preference": "GET_FROM_FILE",
        • "locale": "string",
        • "return_url": "string",
        • "cancel_url": "string"
        }
      },
    • "sofort": {
      • "name": "string",
      • "country_code": "string",
      • "experience_context": {
        • "brand_name": "string",
        • "shipping_preference": "GET_FROM_FILE",
        • "locale": "string",
        • "return_url": "string",
        • "cancel_url": "string"
        }
      },
    • "trustly": {
      • "name": "string",
      • "country_code": "string",
      • "experience_context": {
        • "brand_name": "string",
        • "shipping_preference": "GET_FROM_FILE",
        • "locale": "string",
        • "return_url": "string",
        • "cancel_url": "string"
        }
      },
    • "venmo": {
      • "experience_context": {
        • "brand_name": "string",
        • "shipping_preference": "GET_FROM_FILE"
        },
      • "vault_id": "string",
      • "email_address": "string",
      • "attributes": {
        • "customer": {
          • "id": "string"
          },
        • "vault": {
          • "store_in_vault": "ON_SUCCESS",
          • "description": "string",
          • "usage_pattern": "string",
          • "usage_type": "string",
          • "customer_type": "CONSUMER",
          • "permit_multiple_payment_tokens": false
          }
        }
      }
    }
}
Response samples
application/json
{
  • "id": "5O190127TN364715T",
  • "status": "COMPLETED",
  • "payment_source": {
    • "paypal": {
      • "name": {
        • "given_name": "John",
        • "surname": "Doe"
        },
      • "email_address": "customer@example.com",
      • "account_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": []
            }
          ]
        }
      }
    ],
  • "payer": {
    • "name": {
      • "given_name": "John",
      • "surname": "Doe"
      },
    • "email_address": "customer@example.com",
    • "payer_id": "QYR5Z8XDVJNXQ"
    },
  • "links": []
}

Definitions

account_id

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.

string <ppaas_payer_id_v3> (account_id) = 13 characters ^[2-9A-HJ-NP-Z]{13}$

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.

"stringstrings"

activity_timestamps

The date and time stamps that are common to authorized payment, captured payment, and refund transactions.

create_time
string <ppaas_date_time_v3> (date_time) [ 20 .. 64 ] characters ^[0-9]{4}-(0[1-9]|1[0-2])-(0[1-9]|[1-2][0-9]|...

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

update_time
string <ppaas_date_time_v3> (date_time) [ 20 .. 64 ] characters ^[0-9]{4}-(0[1-9]|1[0-2])-(0[1-9]|[1-2][0-9]|...

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

{
  • "create_time": "stringstringstringst",
  • "update_time": "stringstringstringst"
}

amount_breakdown

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

object (Money)

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. item_total.value can not be a negative number.

object (Money)

The shipping fee for all items within a given purchase_unit. shipping.value can not be a negative number.

object (Money)

The handling fee for all items within a given purchase_unit. handling.value can not be a negative number.

object (Money)

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. tax_total.value can not be a negative number.

object (Money)

The insurance fee for all items within a given purchase_unit. insurance.value can not be a negative number.

object (Money)

The shipping discount for all items within a given purchase_unit. shipping_discount.value can not be a negative number.

object (Money)

The discount for all items within a given purchase_unit. discount.value can not be a negative number.

{
  • "item_total": {
    • "currency_code": "str",
    • "value": "string"
    },
  • "shipping": {
    • "currency_code": "str",
    • "value": "string"
    },
  • "handling": {
    • "currency_code": "str",
    • "value": "string"
    },
  • "tax_total": {
    • "currency_code": "str",
    • "value": "string"
    },
  • "insurance": {
    • "currency_code": "str",
    • "value": "string"
    },
  • "shipping_discount": {
    • "currency_code": "str",
    • "value": "string"
    },
  • "discount": {
    • "currency_code": "str",
    • "value": "string"
    }
}

amount_with_breakdown

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 minus discount.
The amount must be a positive number. For listed of supported currencies and decimal precision, see the PayPal REST APIs Currency Codes.

currency_code
required
string <ppaas_common_currency_code_v2> (currency_code) = 3 characters

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

value
required
string <= 32 characters ^((-?[0-9]+)|(-?([0-9]+)?[.][0-9]+))$

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.

object (amount_breakdown)

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

{
  • "currency_code": "str",
  • "value": "string",
  • "breakdown": {
    • "item_total": {
      • "currency_code": "str",
      • "value": "string"
      },
    • "shipping": {
      • "currency_code": "str",
      • "value": "string"
      },
    • "handling": {
      • "currency_code": "str",
      • "value": "string"
      },
    • "tax_total": {
      • "currency_code": "str",
      • "value": "string"
      },
    • "insurance": {
      • "currency_code": "str",
      • "value": "string"
      },
    • "shipping_discount": {
      • "currency_code": "str",
      • "value": "string"
      },
    • "discount": {
      • "currency_code": "str",
      • "value": "string"
      }
    }
}

apple_pay_payment_data

Information about the decrypted apple pay payment data for the token like cryptogram, eci indicator.

cryptogram
string [ 1 .. 2000 ] characters ^.*$

Online payment cryptogram, as defined by 3D Secure. The pattern is defined by an external party and supports Unicode.

eci_indicator
string [ 1 .. 256 ] characters ^.*$

ECI indicator, as defined by 3- Secure. The pattern is defined by an external party and supports Unicode.

emv_data
string [ 1 .. 2000 ] characters ^.*$

Encoded Apple Pay EMV Payment Structure used for payments in China. The pattern is defined by an external party and supports Unicode.

pin
string [ 1 .. 2000 ] characters ^.*$

Bank Key encrypted Apple Pay PIN. The pattern is defined by an external party and supports Unicode.

{
  • "cryptogram": "string",
  • "eci_indicator": "string",
  • "emv_data": "string",
  • "pin": "string"
}

application_context

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

Note: Partners and Marketplaces might configure brand_name and shipping_preference during partner account setup, which overrides the request values.

brand_name
string [ 1 .. 127 ] characters

DEPRECATED. The label that overrides the business name in the PayPal account on the PayPal site. The fields in application_context are now available in the experience_context object under the payment_source which supports them (eg. payment_source.paypal.experience_context.brand_name). Please specify this field in the experience_context object instead of the application_context object.

landing_page
string [ 1 .. 13 ] characters ^[0-9A-Z_]+$
Default: "NO_PREFERENCE"

DEPRECATED. DEPRECATED. The type of landing page to show on the PayPal site for customer checkout. The fields in application_context are now available in the experience_context object under the payment_source which supports them (eg. payment_source.paypal.experience_context.landing_page). Please specify this field in the experience_context object instead of the application_context object.

Enum: Description
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.

NO_PREFERENCE

When the customer clicks PayPal Checkout, the customer is redirected to either a page to log in to PayPal and approve the payment or to a page to enter credit or debit card and other relevant billing information required to complete the purchase, depending on their previous interaction with PayPal.

shipping_preference
string [ 1 .. 20 ] characters ^[0-9A-Z_]+$
Default: "GET_FROM_FILE"

DEPRECATED. DEPRECATED. 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 fields in application_context are now available in the experience_context object under the payment_source which supports them (eg. payment_source.paypal.experience_context.shipping_preference). Please specify this field in the experience_context object instead of the application_context object.

Enum: Description
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.

user_action
string [ 1 .. 8 ] characters ^[0-9A-Z_]+$
Default: "CONTINUE"

DEPRECATED. Configures a Continue or Pay Now checkout flow. The fields in application_context are now available in the experience_context object under the payment_source which supports them (eg. payment_source.paypal.experience_context.user_action). Please specify this field in the experience_context object instead of the application_context object.

Enum: Description
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.

return_url
string <uri>

DEPRECATED. The URL where the customer is redirected after the customer approves the payment. The fields in application_context are now available in the experience_context object under the payment_source which supports them (eg. payment_source.paypal.experience_context.return_url). Please specify this field in the experience_context object instead of the application_context object.

cancel_url
string <uri>

DEPRECATED. The URL where the customer is redirected after the customer cancels the payment. The fields in application_context are now available in the experience_context object under the payment_source which supports them (eg. payment_source.paypal.experience_context.cancel_url). Please specify this field in the experience_context object instead of the application_context object.

locale
string <ppaas_common_language_v3> (language_v3) [ 2 .. 10 ] characters ^[a-z]{2}(?:-[A-Z][a-z]{3})?(?:-(?:[A-Z]{2}|[...

DEPRECATED. 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. The fields in application_context are now available in the experience_context object under the payment_source which supports them (eg. payment_source.paypal.experience_context.locale). Please specify this field in the experience_context object instead of the application_context object.

object (payment_method)

DEPRECATED. The customer and merchant payment preferences. The fields in application_context are now available in the experience_context object under the payment_source which supports them (eg. payment_source.paypal.experience_context.payment_method_selected). Please specify this field in the experience_context object instead of the application_context object..

object (stored_payment_source)

Provides additional details to process a payment using a payment_source that has been stored or is intended to be stored (also referred to as stored_credential or card-on-file).
Parameter compatibility:

  • payment_type=ONE_TIME is compatible only with payment_initiator=CUSTOMER.
  • usage=FIRST is compatible only with payment_initiator=CUSTOMER.
  • previous_transaction_reference or previous_network_transaction_reference is compatible only with payment_initiator=MERCHANT.
  • Only one of the parameters - previous_transaction_reference and previous_network_transaction_reference - can be present in the request.

{
  • "brand_name": "string",
  • "landing_page": "LOGIN",
  • "shipping_preference": "GET_FROM_FILE",
  • "user_action": "CONTINUE",
  • "return_url": "http://example.com",
  • "cancel_url": "http://example.com",
  • "locale": "string",
  • "payment_method": {
    • "standard_entry_class_code": "TEL",
    • "payee_preferred": "UNRESTRICTED"
    },
  • "stored_payment_source": {
    • "payment_initiator": "CUSTOMER",
    • "payment_type": "ONE_TIME",
    • "usage": "FIRST",
    • "previous_network_transaction_reference": {
      • "id": "stringstr",
      • "date": "stri",
      • "network": "VISA"
      }
    }
}

authentication_response

Results of Authentication such as 3D Secure.

liability_shift
string (liability_shift) [ 1 .. 255 ] characters ^[0-9A-Z_]+$

Liability shift indicator. The outcome of the issuer's authentication.

Enum: Description
YES

Liability has shifted to the card issuer. Available only after order is authorized or captured.

NO

Liability is with the merchant.

POSSIBLE

Liability may shift to the card issuer. Available only before order is authorized or captured.

UNKNOWN

The authentication system is not available.

object (three_d_secure_authentication_response)

Results of 3D Secure Authentication.

{
  • "liability_shift": "YES",
  • "three_d_secure": {
    • "authentication_status": "Y",
    • "enrollment_status": "Y"
    }
}

authorization

The authorized payment transaction.

status
string

The status for the authorized payment.

Enum: Description
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.

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.

PENDING

The created authorization is in pending state. For more information, see status.details.

object (authorization_status_details)

The details of the authorized order pending status.

id
string

The PayPal-generated ID for the authorized payment.

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.

custom_id
string <= 127 characters

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

Array of objects (Link Description)

An array of related HATEOAS links.

object (Money)

The amount for this authorized payment.

object (seller_protection)

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

expiration_time
string <ppaas_date_time_v3> (date_time) [ 20 .. 64 ] characters ^[0-9]{4}-(0[1-9]|1[0-2])-(0[1-9]|[1-2][0-9]|...

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

create_time
string <ppaas_date_time_v3> (date_time) [ 20 .. 64 ] characters ^[0-9]{4}-(0[1-9]|1[0-2])-(0[1-9]|[1-2][0-9]|...

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

update_time
string <ppaas_date_time_v3> (date_time) [ 20 .. 64 ] characters ^[0-9]{4}-(0[1-9]|1[0-2])-(0[1-9]|[1-2][0-9]|...

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

{
  • "status": "CREATED",
  • "status_details": {
    • "reason": "PENDING_REVIEW"
    },
  • "id": "string",
  • "invoice_id": "string",
  • "custom_id": "string",
  • "links": [
    • {
      • "href": "string",
      • "rel": "string",
      • "method": "GET"
      }
    ],
  • "amount": {
    • "currency_code": "str",
    • "value": "string"
    },
  • "seller_protection": {
    • "status": "ELIGIBLE",
    • "dispute_categories": [
      • "string"
      ]
    },
  • "expiration_time": "string",
  • "create_time": "stringstringstringst",
  • "update_time": "stringstringstringst"
}

authorization_status

The status fields for an authorized payment.

status
string

The status for the authorized payment.

Enum: Description
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.

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.

PENDING

The created authorization is in pending state. For more information, see status.details.

object (authorization_status_details)

The details of the authorized order pending status.

{
  • "status": "CREATED",
  • "status_details": {
    • "reason": "PENDING_REVIEW"
    }
}

authorization_status_details

The details of the authorized payment status.

reason
string [ 1 .. 24 ] characters ^[A-Z_]+$

The reason why the authorized status is PENDING.

Value: Description
PENDING_REVIEW

Authorization is pending manual review.

{
  • "reason": "PENDING_REVIEW"
}

authorization_with_additional_data

The authorization with additional payment details, such as risk assessment and processor response. These details are populated only for certain payment methods.

status
string

The status for the authorized payment.

Enum: Description
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.

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.

PENDING

The created authorization is in pending state. For more information, see status.details.

object (authorization_status_details)

The details of the authorized order pending status.

id
string

The PayPal-generated ID for the authorized payment.

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.

custom_id
string <= 127 characters

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

Array of objects (Link Description)

An array of related HATEOAS links.

object (Money)

The amount for this authorized payment.

object (seller_protection)

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

expiration_time
string <ppaas_date_time_v3> (date_time) [ 20 .. 64 ] characters ^[0-9]{4}-(0[1-9]|1[0-2])-(0[1-9]|[1-2][0-9]|...

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

create_time
string <ppaas_date_time_v3> (date_time) [ 20 .. 64 ] characters ^[0-9]{4}-(0[1-9]|1[0-2])-(0[1-9]|[1-2][0-9]|...

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

update_time
string <ppaas_date_time_v3> (date_time) [ 20 .. 64 ] characters ^[0-9]{4}-(0[1-9]|1[0-2])-(0[1-9]|[1-2][0-9]|...

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

object (processor_response)

The processor response information for payment requests, such as direct credit card transactions.

{
  • "status": "CREATED",
  • "status_details": {
    • "reason": "PENDING_REVIEW"
    },
  • "id": "string",
  • "invoice_id": "string",
  • "custom_id": "string",
  • "links": [
    • {
      • "href": "string",
      • "rel": "string",
      • "method": "GET"
      }
    ],
  • "amount": {
    • "currency_code": "str",
    • "value": "string"
    },
  • "seller_protection": {
    • "status": "ELIGIBLE",
    • "dispute_categories": [
      • "string"
      ]
    },
  • "expiration_time": "string",
  • "create_time": "stringstringstringst",
  • "update_time": "stringstringstringst",
  • "processor_response": {
    • "avs_code": "A",
    • "cvv_code": "E",
    • "response_code": "0000",
    • "payment_advice_code": "01"
    }
}

Authorize Request

The authorization of an order request.

object (payment_source)

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.

{
  • "payment_source": {
    • "card": {
      • "name": "string",
      • "number": "stringstrings",
      • "security_code": "stri",
      • "expiry": "string",
      • "billing_address": {
        • "address_line_1": "string",
        • "address_line_2": "string",
        • "admin_area_2": "string",
        • "admin_area_1": "string",
        • "postal_code": "string",
        • "country_code": "st"
        },
      • "attributes": {
        • "customer": {
          • "id": "string",
          • "email_address": "string",
          • "phone": {
            • "phone_type": "FAX",
            • "phone_number": {
              • "national_number": "string"
              }
            }
          },
        • "vault": {
          • "store_in_vault": "ON_SUCCESS"
          }
        },
      • "stored_credential": {
        • "payment_initiator": "CUSTOMER",
        • "payment_type": "ONE_TIME",
        • "usage": "FIRST",
        • "previous_network_transaction_reference": {
          • "id": "stringstr",
          • "date": "stri",
          • "network": "VISA"
          }
        },
      • "vault_id": "string"
      },
    • "token": {
      • "id": "string",
      • "type": "BILLING_AGREEMENT"
      },
    • "paypal": {
      • "experience_context": {
        • "brand_name": "string",
        • "shipping_preference": "GET_FROM_FILE",
        • "landing_page": "LOGIN",
        • "user_action": "CONTINUE",
        • "payment_method_preference": "UNRESTRICTED",
        • "locale": "string",
        • "return_url": "string",
        • "cancel_url": "string"
        },
      • "billing_agreement_id": "string",
      • "vault_id": "string",
      • "email_address": "string",
      • "name": {
        • "given_name": "string",
        • "surname": "string"
        },
      • "phone": {
        • "phone_type": "FAX",
        • "phone_number": {
          • "national_number": "string"
          }
        },
      • "birth_date": "stringstri",
      • "tax_info": {
        • "tax_id": "string",
        • "tax_id_type": "BR_CPF"
        },
      • "address": {
        • "address_line_1": "string",
        • "address_line_2": "string",
        • "admin_area_2": "string",
        • "admin_area_1": "string",
        • "postal_code": "string",
        • "country_code": "st"
        },
      • "attributes": {
        • "customer": {
          • "id": "string"
          },
        • "vault": {
          • "store_in_vault": "ON_SUCCESS",
          • "description": "string",
          • "usage_pattern": "string",
          • "usage_type": "string",
          • "customer_type": "CONSUMER",
          • "permit_multiple_payment_tokens": false
          }
        }
      },
    • "bancontact": {
      • "name": "string",
      • "country_code": "string",
      • "experience_context": {
        • "brand_name": "string",
        • "shipping_preference": "GET_FROM_FILE",
        • "locale": "string",
        • "return_url": "string",
        • "cancel_url": "string"
        }
      },
    • "blik": {
      • "name": "string",
      • "country_code": "string",
      • "email": "string",
      • "experience_context": {
        • "brand_name": "string",
        • "shipping_preference": "GET_FROM_FILE",
        • "locale": "string",
        • "return_url": "string",
        • "cancel_url": "string"
        }
      },
    • "eps": {
      • "name": "string",
      • "country_code": "string",
      • "experience_context": {
        • "brand_name": "string",
        • "shipping_preference": "GET_FROM_FILE",
        • "locale": "string",
        • "return_url": "string",
        • "cancel_url": "string"
        }
      },
    • "giropay": {
      • "name": "string",
      • "country_code": "string",
      • "experience_context": {
        • "brand_name": "string",
        • "shipping_preference": "GET_FROM_FILE",
        • "locale": "string",
        • "return_url": "string",
        • "cancel_url": "string"
        }
      },
    • "ideal": {
      • "name": "string",
      • "country_code": "string",
      • "bic": "string",
      • "experience_context": {
        • "brand_name": "string",
        • "shipping_preference": "GET_FROM_FILE",
        • "locale": "string",
        • "return_url": "string",
        • "cancel_url": "string"
        }
      },
    • "mybank": {
      • "name": "string",
      • "country_code": "string",
      • "experience_context": {
        • "brand_name": "string",
        • "shipping_preference": "GET_FROM_FILE",
        • "locale": "string",
        • "return_url": "string",
        • "cancel_url": "string"
        }
      },
    • "p24": {
      • "name": "string",
      • "email": "string",
      • "country_code": "string",
      • "experience_context": {
        • "brand_name": "string",
        • "shipping_preference": "GET_FROM_FILE",
        • "locale": "string",
        • "return_url": "string",
        • "cancel_url": "string"
        }
      },
    • "sofort": {
      • "name": "string",
      • "country_code": "string",
      • "experience_context": {
        • "brand_name": "string",
        • "shipping_preference": "GET_FROM_FILE",
        • "locale": "string",
        • "return_url": "string",
        • "cancel_url": "string"
        }
      },
    • "trustly": {
      • "name": "string",
      • "country_code": "string",
      • "experience_context": {
        • "brand_name": "string",
        • "shipping_preference": "GET_FROM_FILE",
        • "locale": "string",
        • "return_url": "string",
        • "cancel_url": "string"
        }
      },
    • "venmo": {
      • "experience_context": {
        • "brand_name": "string",
        • "shipping_preference": "GET_FROM_FILE"
        },
      • "vault_id": "string",
      • "email_address": "string",
      • "attributes": {
        • "customer": {
          • "id": "string"
          },
        • "vault": {
          • "store_in_vault": "ON_SUCCESS",
          • "description": "string",
          • "usage_pattern": "string",
          • "usage_type": "string",
          • "customer_type": "CONSUMER",
          • "permit_multiple_payment_tokens": false
          }
        }
      }
    }
}

bancontact

Information used to pay Bancontact.

card_last_digits
string = 4 characters [0-9]{4}

The last digits of the card used to fund the Bancontact payment.

name
string (name) [ 3 .. 300 ] characters

The name of the account holder associated with this payment method.

country_code
string <ppaas_common_country_code_v2> (country_code_v3) = 2 characters ^([A-Z]{2}|C2)$

The two-character ISO 3166-1 country code.

bic
string (BIC) [ 8 .. 11 ] characters ^[A-Z-a-z0-9]{4}[A-Z-a-z]{2}[A-Z-a-z0-9]{2}([...

The bank identification code (BIC).

iban_last_chars
string (iban_last_chars) [ 4 .. 34 ] characters [a-zA-Z0-9]{4}

The last characters of the IBAN used to pay.

{
  • "card_last_digits": "stri",
  • "name": "string",
  • "country_code": "string",
  • "bic": "string",
  • "iban_last_chars": "string"
}

bancontact_request

Information needed to pay using Bancontact.

name
required
string (name) [ 3 .. 300 ] characters

The name of the account holder associated with this payment method.

country_code
required
string <ppaas_common_country_code_v2> (country_code_v3) = 2 characters ^([A-Z]{2}|C2)$

The two-character ISO 3166-1 country code.

object (experience_context_base)

Customizes the payer experience during the approval process for the payment.

{
  • "name": "string",
  • "country_code": "string",
  • "experience_context": {
    • "brand_name": "string",
    • "shipping_preference": "GET_FROM_FILE",
    • "locale": "string",
    • "return_url": "string",
    • "cancel_url": "string"
    }
}

BIC

The business identification code (BIC). In payments systems, a BIC is used to identify a specific business, most commonly a bank.

string (BIC) [ 8 .. 11 ] characters ^[A-Z-a-z0-9]{4}[A-Z-a-z]{2}[A-Z-a-z0-9]{2}([...

The business identification code (BIC). In payments systems, a BIC is used to identify a specific business, most commonly a bank.

"stringst"

billing_agreement_id

The PayPal billing agreement ID. References an approved recurring payment for goods or services.

string (billing_agreement_id) [ 2 .. 128 ] characters ^[a-zA-Z0-9-]+$

The PayPal billing agreement ID. References an approved recurring payment for goods or services.

"string"

blik

Information used to pay using BLIK.

name
string (name) [ 3 .. 300 ] characters

The name of the account holder associated with this payment method.

country_code
string <ppaas_common_country_code_v2> (country_code_v3) = 2 characters ^([A-Z]{2}|C2)$

The two-character ISO 3166-1 country code.

email
string <ppaas_common_email_address_v2> (email_address) [ 3 .. 254 ] characters ^.+@[^"\-].+$

The email address of the account holder associated with this payment method.

{
  • "name": "string",
  • "country_code": "string",
  • "email": "string"
}

blik_request

Information needed to pay using BLIK.

name
required
string (name) [ 3 .. 300 ] characters

The name of the account holder associated with this payment method.

country_code
required
string <ppaas_common_country_code_v2> (country_code_v3) = 2 characters ^([A-Z]{2}|C2)$

The two-character ISO 3166-1 country code.

email
string <ppaas_common_email_address_v2> (email_address) [ 3 .. 254 ] characters ^.+@[^"\-].+$

The email address of the account holder associated with this payment method.

object (experience_context_base)

Customizes the payer experience during the approval process for the payment.

{
  • "name": "string",
  • "country_code": "string",
  • "email": "string",
  • "experience_context": {
    • "brand_name": "string",
    • "shipping_preference": "GET_FROM_FILE",
    • "locale": "string",
    • "return_url": "string",
    • "cancel_url": "string"
    }
}

capture

A captured payment.

status
string

The status of the captured payment.

Enum: Description
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.

FAILED

There was an error while capturing payment.

object (capture_status_details)

The details of the captured payment status.

id
string

The PayPal-generated ID for the captured payment.

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.

custom_id
string <= 127 characters

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

final_capture
boolean
Default: false

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.

disbursement_mode
string (disbursement_mode) [ 1 .. 16 ] characters ^[A-Z_]+$
Default: "INSTANT"

The funds that are held on behalf of the merchant.

Enum: Description
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.

Array of objects (Link Description)

An array of related HATEOAS links.

object (Money)

The amount for this captured payment.

object (seller_protection)

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

object (Seller Receivable Breakdown)

The detailed breakdown of the capture activity. This is not available for transactions that are in pending state.

object (processor_response)

An object that provides additional processor information for a direct credit card transaction.

create_time
string <ppaas_date_time_v3> (date_time) [ 20 .. 64 ] characters ^[0-9]{4}-(0[1-9]|1[0-2])-(0[1-9]|[1-2][0-9]|...

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

update_time
string <ppaas_date_time_v3> (date_time) [ 20 .. 64 ] characters ^[0-9]{4}-(0[1-9]|1[0-2])-(0[1-9]|[1-2][0-9]|...

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

{
  • "status": "COMPLETED",
  • "status_details": {
    • "reason": "BUYER_COMPLAINT"
    },
  • "id": "string",
  • "invoice_id": "string",
  • "custom_id": "string",
  • "final_capture": false,
  • "disbursement_mode": "INSTANT",
  • "links": [
    • {
      • "href": "string",
      • "rel": "string",
      • "method": "GET"
      }
    ],
  • "amount": {
    • "currency_code": "str",
    • "value": "string"
    },
  • "seller_protection": {
    • "status": "ELIGIBLE",
    • "dispute_categories": [
      • "string"
      ]
    },
  • "seller_receivable_breakdown": {
    • "platform_fees": [
      • {
        • "amount": {
          • "currency_code": "str",
          • "value": "string"
          },
        • "payee": {
          • "email_address": "string",
          • "merchant_id": "stringstrings"
          }
        }
      ],
    • "gross_amount": {
      • "currency_code": "str",
      • "value": "string"
      },
    • "paypal_fee": {
      • "currency_code": "str",
      • "value": "string"
      },
    • "paypal_fee_in_receivable_currency": {
      • "currency_code": "str",
      • "value": "string"
      },
    • "net_amount": {
      • "currency_code": "str",
      • "value": "string"
      },
    • "receivable_amount": {
      • "currency_code": "str",
      • "value": "string"
      },
    • "exchange_rate": {
      • "value": "string",
      • "source_currency": "str",
      • "target_currency": "str"
      }
    },
  • "processor_response": {
    • "avs_code": "A",
    • "cvv_code": "E",
    • "response_code": "0000",
    • "payment_advice_code": "01"
    },
  • "create_time": "stringstringstringst",
  • "update_time": "stringstringstringst"
}

capture_status

The status of a captured payment.

status
string

The status of the captured payment.

Enum: Description
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.

FAILED

There was an error while capturing payment.

object (capture_status_details)

The details of the captured payment status.

{
  • "status": "COMPLETED",
  • "status_details": {
    • "reason": "BUYER_COMPLAINT"
    }
}

capture_status_details

The details of the captured payment status.

reason
string [ 1 .. 64 ] characters ^[A-Z_]+$

The reason why the captured payment status is PENDING or DENIED.

Enum: Description
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.

{
  • "reason": "BUYER_COMPLAINT"
}

card

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

name
string [ 1 .. 300 ] characters ^.{1,300}$

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

number
string [ 13 .. 19 ] characters ^[0-9]{13,19}$

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

security_code
string [ 3 .. 4 ] characters ^[0-9]{3,4}$

The three- or four-digit security code of the card. Also known as the CVV, CVC, CVN, CVE, or CID. This parameter cannot be present in the request when payment_initiator=MERCHANT.

expiry
string (date_year_month) = 7 characters ^[0-9]{4}-(0[1-9]|1[0-2])$

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

object (Portable Postal Address (Medium-Grained))

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.

object (card_attributes)

Additional attributes associated with the use of this card.

{
  • "name": "string",
  • "number": "stringstrings",
  • "security_code": "stri",
  • "expiry": "string",
  • "billing_address": {
    • "address_line_1": "string",
    • "address_line_2": "string",
    • "admin_area_2": "string",
    • "admin_area_1": "string",
    • "postal_code": "string",
    • "country_code": "st"
    },
  • "attributes": {
    • "customer": {
      • "id": "string",
      • "email_address": "string",
      • "phone": {
        • "phone_type": "FAX",
        • "phone_number": {
          • "national_number": "string"
          }
        }
      },
    • "vault": {
      • "store_in_vault": "ON_SUCCESS"
      }
    }
}

card_attributes

Additional attributes associated with the use of this card.

object (customer)

The details about a customer in PayPal's system of record.

object (vault_instruction_base)

Instruction to vault the card based on the specified strategy.

{
  • "customer": {
    • "id": "string",
    • "email_address": "string",
    • "phone": {
      • "phone_type": "FAX",
      • "phone_number": {
        • "national_number": "string"
        }
      }
    },
  • "vault": {
    • "store_in_vault": "ON_SUCCESS"
    }
}

card_attributes_response

Additional attributes associated with the use of this card.

object (vault_response)

The details about a saved payment source.

{
  • "vault": {
    • "id": "string",
    • "status": "VAULTED",
    • "links": [
      • {
        • "href": "string",
        • "rel": "string",
        • "method": "GET"
        }
      ],
    • "customer": {
      • "id": "string"
      }
    }
}

card_brand

The card network or brand. Applies to credit, debit, gift, and payment cards.

string (card_brand) [ 1 .. 255 ] characters ^[A-Z_]+$

The card network or brand. Applies to credit, debit, gift, and payment cards.

Enum: Description
VISA

Visa card.

MASTERCARD

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

"VISA"

card_from_request

Representation of card details as received in the request.

last_digits
string [ 2 .. 4 ] characters [0-9]{2,}

The last digits of the payment card.

expiry
string (date_year_month) = 7 characters ^[0-9]{4}-(0[1-9]|1[0-2])$

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

{
  • "last_digits": "stri",
  • "expiry": "string"
}

card_request

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

Note: Passing card number, cvv and expiry directly via the API requires PCI SAQ D compliance.
PayPal offers a mechanism by which you do not have to take on the PCI SAQ D burden by using hosted fields - refer to this Integration Guide.

name
string [ 1 .. 300 ] characters ^.{1,300}$

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

number
string [ 13 .. 19 ] characters ^[0-9]{13,19}$

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

security_code
string [ 3 .. 4 ] characters ^[0-9]{3,4}$

The three- or four-digit security code of the card. Also known as the CVV, CVC, CVN, CVE, or CID. This parameter cannot be present in the request when payment_initiator=MERCHANT.

expiry
string (date_year_month) = 7 characters ^[0-9]{4}-(0[1-9]|1[0-2])$

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

object (Portable Postal Address (Medium-Grained))

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.

object (card_attributes)

Additional attributes associated with the use of this card.

object (card_stored_credential)

Provides additional details to process a payment using a card that has been stored or is intended to be stored (also referred to as stored_credential or card-on-file).
Parameter compatibility:

  • payment_type=ONE_TIME is compatible only with payment_initiator=CUSTOMER.
  • usage=FIRST is compatible only with payment_initiator=CUSTOMER.
  • previous_transaction_reference or previous_network_transaction_reference is compatible only with payment_initiator=MERCHANT.
  • Only one of the parameters - previous_transaction_reference and previous_network_transaction_reference - can be present in the request.

vault_id
string (vault_id) [ 1 .. 255 ] characters ^[0-9a-zA-Z_-]+$

The PayPal-generated ID for the saved card payment source. Typically stored on the merchant's server.

{
  • "name": "string",
  • "number": "stringstrings",
  • "security_code": "stri",
  • "expiry": "string",
  • "billing_address": {
    • "address_line_1": "string",
    • "address_line_2": "string",
    • "admin_area_2": "string",
    • "admin_area_1": "string",
    • "postal_code": "string",
    • "country_code": "st"
    },
  • "attributes": {
    • "customer": {
      • "id": "string",
      • "email_address": "string",
      • "phone": {
        • "phone_type": "FAX",
        • "phone_number": {
          • "national_number": "string"
          }
        }
      },
    • "vault": {
      • "store_in_vault": "ON_SUCCESS"
      }
    },
  • "stored_credential": {
    • "payment_initiator": "CUSTOMER",
    • "payment_type": "ONE_TIME",
    • "usage": "FIRST",
    • "previous_network_transaction_reference": {
      • "id": "stringstr",
      • "date": "stri",
      • "network": "VISA"
      }
    },
  • "vault_id": "string"
}

card_response

The payment card to use to fund a payment. Card can be a credit or debit card.

name
string [ 2 .. 300 ] characters

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

last_digits
string[0-9]{2,}

The last digits of the payment card.

type
string

The payment card type.

Enum: Description
CREDIT

A credit card.

DEBIT

A debit card.

PREPAID

A Prepaid card.

UNKNOWN

Card type cannot be determined.

object (card_from_request)

Representation of card details as received in the request.

brand
string (card_brand) [ 1 .. 255 ] characters ^[A-Z_]+$

The card brand or network. Typically used in the response.

Enum: Description
VISA

Visa card.

MASTERCARD

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

object (authentication_response)

Results of Authentication such as 3D Secure.

object (card_attributes_response)

Additional attributes associated with the use of this card.

expiry
string (date_year_month) = 7 characters ^[0-9]{4}-(0[1-9]|1[0-2])$

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

{
  • "name": "string",
  • "last_digits": "string",
  • "type": "CREDIT",
  • "from_request": {
    • "last_digits": "stri",
    • "expiry": "string"
    },
  • "brand": "VISA",
  • "authentication_result": {
    • "liability_shift": "YES",
    • "three_d_secure": {
      • "authentication_status": "Y",
      • "enrollment_status": "Y"
      }
    },
  • "attributes": {
    • "vault": {
      • "id": "string",
      • "status": "VAULTED",
      • "links": [
        • {
          • "href": "string",
          • "rel": "string",
          • "method": "GET"
          }
        ],
      • "customer": {
        • "id": "string"
        }
      }
    },
  • "expiry": "string"
}

card_stored_credential

Provides additional details to process a payment using a card that has been stored or is intended to be stored (also referred to as stored_credential or card-on-file).
Parameter compatibility:

  • payment_type=ONE_TIME is compatible only with payment_initiator=CUSTOMER.
  • usage=FIRST is compatible only with payment_initiator=CUSTOMER.
  • previous_transaction_reference or previous_network_transaction_reference is compatible only with payment_initiator=MERCHANT.
  • Only one of the parameters - previous_transaction_reference and previous_network_transaction_reference - can be present in the request.

payment_initiator
required
string (payment_initiator) [ 1 .. 255 ] characters ^[0-9A-Z_]+$

The person or party who initiated or triggered the payment.

Enum: Description
CUSTOMER

Payment is initiated with the active engagement of the customer. e.g. a customer checking out on a merchant website.

MERCHANT

Payment is initiated by merchant on behalf of the customer without the active engagement of customer. e.g. a merchant charging the monthly payment of a subscription to the customer.

payment_type
required
string (stored_payment_source_payment_type) [ 1 .. 255 ] characters ^[0-9A-Z_]+$

Indicates the type of the stored payment_source payment.

Enum: Description
ONE_TIME

One Time payment such as online purchase or donation. (e.g. Checkout with one-click).

RECURRING

Payment which is part of a series of payments with fixed or variable amounts, following a fixed time interval. (e.g. Subscription payments).

UNSCHEDULED

Payment which is part of a series of payments that occur on a non-fixed schedule and/or have variable amounts. (e.g. Account Topup payments).

usage
string (stored_payment_source_usage_type) [ 1 .. 255 ] characters ^[0-9A-Z_]+$
Default: "DERIVED"

Indicates if this is a first or subsequent payment using a stored payment source (also referred to as stored credential or card on file).

Enum: Description
FIRST

Indicates the Initial/First payment with a payment_source that is intended to be stored upon successful processing of the payment.

SUBSEQUENT

Indicates a payment using a stored payment_source which has been successfully used previously for a payment.

DERIVED

Indicates that PayPal will derive the value of FIRST or SUBSEQUENT based on data available to PayPal.

object (network_transaction_reference)

Reference values used by the card network to identify a transaction.

{
  • "payment_initiator": "CUSTOMER",
  • "payment_type": "ONE_TIME",
  • "usage": "FIRST",
  • "previous_network_transaction_reference": {
    • "id": "stringstr",
    • "date": "stri",
    • "network": "VISA"
    }
}

card_supplementary_data

Supplementary data associated with the card.

object (level_2)

The level 2 card processing data collections. If your merchant account has been configured for Level 2 processing this field will be passed to the processor on your behalf. Please contact your PayPal Technical Account Manager to define level 2 data for your business.

object (level_3)

The level 3 card processing data collections, If your merchant account has been configured for Level 3 processing this field will be passed to the processor on your behalf. Please contact your PayPal Technical Account Manager to define level 3 data for your business.

{
  • "level_2": {
    • "invoice_id": "string",
    • "tax_total": {
      • "currency_code": "str",
      • "value": "string"
      }
    },
  • "level_3": {
    • "ships_from_postal_code": "string",
    • "line_items": [
      • {
        • "name": "string",
        • "quantity": "string",
        • "description": "string",
        • "sku": "string",
        • "category": "DIGITAL_GOODS",
        • "unit_amount": {
          • "currency_code": "str",
          • "value": "string"
          },
        • "tax": {
          • "currency_code": "str",
          • "value": "string"
          },
        • "commodity_code": "string",
        • "unit_of_measure": "string",
        • "discount_amount": {
          • "currency_code": "str",
          • "value": "string"
          },
        • "total_amount": {
          • "currency_code": "str",
          • "value": "string"
          }
        }
      ],
    • "shipping_amount": {
      • "currency_code": "str",
      • "value": "string"
      },
    • "duty_amount": {
      • "currency_code": "str",
      • "value": "string"
      },
    • "discount_amount": {
      • "currency_code": "str",
      • "value": "string"
      },
    • "shipping_address": {
      • "address_line_1": "string",
      • "address_line_2": "string",
      • "admin_area_2": "string",
      • "admin_area_1": "string",
      • "postal_code": "string",
      • "country_code": "st"
      }
    }
}

card_type

Type of card. i.e Credit, Debit and so on.

string (card_type) [ 1 .. 255 ] characters ^[A-Z_]+$

Type of card. i.e Credit, Debit and so on.

Enum: Description
CREDIT

A credit card.

DEBIT

A debit card.

PREPAID

A Prepaid card.

STORE

A store card.

UNKNOWN

Card type cannot be determined.

"CREDIT"

checkout_payment_intent

The intent to either capture payment immediately or authorize a payment for an order after order creation.

string (checkout_payment_intent)

The intent to either capture payment immediately or authorize a payment for an order after order creation.

Enum: Description
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 best captured within three days of authorization 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. This intent is not supported when you have more than one purchase_unit within your order.

"CAPTURE"

Confirm Application Context

Customizes the payer confirmation experience.

brand_name
string [ 1 .. 127 ] characters

Label to present to your payer as part of the PayPal hosted web experience.

return_url
string <uri> [ 10 .. 4000 ] characters

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

cancel_url
string <uri> [ 10 .. 4000 ] characters

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

locale
string <ppaas_common_language_v3> (language_v3) [ 2 .. 10 ] characters ^[a-z]{2}(?:-[A-Z][a-z]{3})?(?:-(?:[A-Z]{2}|[...