An order represents a payment between two or more parties. Use the Orders API to create, update, retrieve, authorize, and capture 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.
A successful response to an idempotent request returns the HTTP 200 OK
status code with a JSON response body that shows order details.
{- "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",
- "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",
- "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"
}
}
}
}
{- "id": "5O190127TN364715T",
- "status": "PAYER_ACTION_REQUIRED",
- "payment_source": {
- "paypal": { }
}, - "links": [
- {
- "rel": "self",
- "method": "GET"
}, - {
- "rel": "payer-action",
- "method": "GET"
}
]
}
Shows details for an order, by ID.
Note: For error handling and troubleshooting, see Orders v2 errors.
Authorization required | string To make REST API calls, include the bearer token in this header with the |
Content-Type required | string [ 1 .. 255 ] characters ^[A-Za-z0-9/+-]+$ The media type. Required for operations with a request body. The value is |
A successful request returns the HTTP 200 OK
status code and a JSON response body that shows order details.
curl -v -X GET https://api-m.sandbox.paypal.com/v2/checkout/orders/5O190127TN364715T \ -H 'Authorization: Bearer access_token6V7rbVwmlM1gFZKW_8QtzWXqpcwQ6T5vhEGYNJDAAdn3paCgRpdeMdVYmWzgbKSsECednupJ3Zx5Xd-g'
{- "id": "5O190127TN364715T",
- "status": "APPROVED",
- "intent": "CAPTURE",
- "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",
- "amount": {
- "currency_code": "USD",
- "value": "100.00"
}
}
], - "payer": {
- "name": {
- "given_name": "John",
- "surname": "Doe"
}, - "email_address": "customer@example.com",
- "payer_id": "QYR5Z8XDVJNXQ"
}, - "create_time": "2018-04-01T21:18:49Z",
- "links": [
- {
- "rel": "self",
- "method": "GET"
}, - {
- "rel": "approve",
- "method": "GET"
}, - {
- "rel": "update",
- "method": "PATCH"
}, - {
- "rel": "capture",
- "method": "POST"
}
]
}
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:
Attribute | Op | Notes |
---|---|---|
intent | replace | |
payer | replace, add | Using replace op for payer will replace the whole payer object with the value sent in request. |
purchase_units | replace, add | |
purchase_units[].custom_id | replace, add, remove | |
purchase_units[].description | replace, add, remove | |
purchase_units[].payee.email | replace | |
purchase_units[].shipping.name | replace, add | |
purchase_units[].shipping.address | replace, add | |
purchase_units[].shipping.type | replace, add | |
purchase_units[].soft_descriptor | replace, remove | |
purchase_units[].amount | replace | |
purchase_units[].invoice_id | replace, add, remove | |
purchase_units[].payment_instruction | replace | |
purchase_units[].payment_instruction.disbursement_mode | replace | By default, disbursement_mode is INSTANT . |
purchase_units[].payment_instruction.platform_fees | replace, add, remove | |
purchase_units[].supplementary_data.card | replace, add, remove | |
application_context.client_configuration | replace, add |
Authorization required | string To make REST API calls, include the bearer token in this header with the |
Content-Type required | string [ 1 .. 255 ] characters ^[A-Za-z0-9/+-]+$ The media type. Required for operations with a request body. The value is |
op required | string The operation.
| ||||||||||||||||||||||||||
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 | ||||||||||||||||||||||||||
from | string The JSON Pointer to the target document location from which to move the value. Required for the |
A successful request returns the HTTP 204 No Content
status code with an empty object in the JSON response body.
[- {
- "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"
}
}
]
Payer confirms their intent to pay for the the Order with the given payment source.
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 |
Content-Type required | string [ 1 .. 255 ] characters ^[A-Za-z0-9/+-]+$ The media type. Required for operations with a request body. The value is |
Prefer | string [ 1 .. 25 ] characters ^[a-zA-Z=]*$ Default: return=minimal The preferred server response upon successful completion of the request. Value is:
|
processing_instruction | string (Processing Instruction) [ 1 .. 36 ] characters ^[0-9A-Z_]+$ Default: "NO_INSTRUCTION" The instruction to process an order.
| ||||||
object (Confirm Application Context) Customizes the payer confirmation experience. | |||||||
required | object (payment_source) The payment source definition. |
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.
{- "processing_instruction": "ORDER_COMPLETE_ON_PAYMENT_APPROVAL",
- "application_context": {
- "brand_name": "string",
- "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",
- "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
}
}
}
}
}
{- "id": "5O190127TN364715T",
- "status": "PAYER_ACTION_REQUIRED",
- "payment_source": {
- "paypal": {
- "name": {
- "given_name": "John",
- "surname": "Doe"
}, - "email_address": "customer@example.com"
}
}, - "payer": {
- "name": {
- "given_name": "John",
- "surname": "Doe"
}, - "email_address": "customer@example.com"
}, - "links": [
- {
- "rel": "self",
- "method": "GET"
}, - {
- "rel": "payer-action",
- "method": "GET"
}
]
}
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.
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:
|
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 |
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 |
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. |
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.
{- "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
}
}
}
}
}
{- "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",
- "payments": {
- "authorizations": [
- {
- "id": "3C679366HH908993F",
- "status": "CREATED",
- "amount": {
- "currency_code": "USD",
- "value": "100.00"
}, - "seller_protection": {
- "status": "ELIGIBLE",
- "dispute_categories": [
- "ITEM_NOT_RECEIVED",
- "UNAUTHORIZED_TRANSACTION"
]
}, - "expiration_time": "2021-10-08T23:37:39Z",
- "links": [
- {
- "rel": "self",
- "method": "GET"
}, - {
- "rel": "capture",
- "method": "POST"
}, - {
- "rel": "void",
- "method": "POST"
}, - {
- "rel": "up",
- "method": "GET"
}
]
}
]
}
}
], - "payer": {
- "name": {
- "given_name": "John",
- "surname": "Doe"
}, - "email_address": "customer@example.com",
- "payer_id": "QYR5Z8XDVJNXQ"
}, - "links": [
- {
- "rel": "self",
- "method": "GET"
}
]
}
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.
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:
|
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 |
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 |
object (payment_source) The payment source definition. |
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.
{- "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
}
}
}
}
}
{- "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": [
- {
- "rel": "self",
- "method": "GET"
}, - {
- "rel": "refund",
- "method": "POST"
}
]
}
]
}
}
], - "payer": {
- "name": {
- "given_name": "John",
- "surname": "Doe"
}, - "email_address": "customer@example.com",
- "payer_id": "QYR5Z8XDVJNXQ"
}, - "links": [
- {
- "rel": "self",
- "method": "GET"
}
]
}
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.
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"
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"
}
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 | |
object (Money) The shipping fee for all items within a given | |
object (Money) The handling fee for all items within a given | |
object (Money) The total tax for all items. Required if the request includes | |
object (Money) The insurance fee for all items within a given | |
object (Money) The shipping discount for all items within a given | |
object (Money) The discount for all items within a given |
{- "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"
}
}
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:
|
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"
}
}
}
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"
}
Customizes the payer experience during the approval process for the payment with PayPal.
Note: Partners and Marketplaces might configurebrand_name
andshipping_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 | ||||||||
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
| ||||||||
shipping_preference | string [ 1 .. 20 ] characters ^[0-9A-Z_]+$ Default: "GET_FROM_FILE" DEPRECATED. DEPRECATED. The shipping preference:
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.
| ||||||||
user_action | string [ 1 .. 8 ] characters ^[0-9A-Z_]+$ Default: "CONTINUE" DEPRECATED. Configures a Continue or Pay Now checkout flow. The fields in
| ||||||||
return_url | string <uri> DEPRECATED. The URL where the customer is redirected after the customer approves the payment. The fields in | ||||||||
cancel_url | string <uri> DEPRECATED. The URL where the customer is redirected after the customer cancels the payment. The fields in | ||||||||
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, | ||||||||
object (payment_method) DEPRECATED. The customer and merchant payment preferences. The fields in | |||||||||
object (stored_payment_source) Provides additional details to process a payment using a
|
{- "brand_name": "string",
- "landing_page": "LOGIN",
- "shipping_preference": "GET_FROM_FILE",
- "user_action": "CONTINUE",
- "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"
}
}
}
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.
| ||||||||||
object (three_d_secure_authentication_response) Results of 3D Secure Authentication. |
{- "liability_shift": "YES",
- "three_d_secure": {
- "authentication_status": "Y",
- "enrollment_status": "Y"
}
}
The authorized payment transaction.
status | string The status for the authorized payment.
| ||||||||||||||
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"
}
The status fields for an authorized payment.
status | string The status for the authorized payment.
| ||||||||||||||
object (authorization_status_details) The details of the authorized order pending status. |
{- "status": "CREATED",
- "status_details": {
- "reason": "PENDING_REVIEW"
}
}
The details of the authorized payment status.
reason | string [ 1 .. 24 ] characters ^[A-Z_]+$ The reason why the authorized status is
|
{- "reason": "PENDING_REVIEW"
}
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.
| ||||||||||||||
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"
}
}
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
}
}
}
}
}
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"
}
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"
}
}
The business identification code (BIC). In payments systems, a BIC is used to identify a specific business, most commonly a bank.
The business identification code (BIC). In payments systems, a BIC is used to identify a specific business, most commonly a bank.
"stringst"
The PayPal billing agreement ID. References an approved recurring payment for goods or services.
The PayPal billing agreement ID. References an approved recurring payment for goods or services.
"string"
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. |
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"
}
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. |
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"
}
}
A captured payment.
status | string The status of the captured 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 | ||||||||||||||
disbursement_mode | string (disbursement_mode) [ 1 .. 16 ] characters ^[A-Z_]+$ Default: "INSTANT" The funds that are held on behalf of the merchant.
| ||||||||||||||
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"
}
The status of a captured payment.
status | string The status of the captured payment.
| ||||||||||||||
object (capture_status_details) The details of the captured payment status. |
{- "status": "COMPLETED",
- "status_details": {
- "reason": "BUYER_COMPLAINT"
}
}
The details of the captured payment status.
reason | string [ 1 .. 64 ] characters ^[A-Z_]+$ The reason why the captured payment status is
|
{- "reason": "BUYER_COMPLAINT"
}
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 |
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 | |
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"
}
}
}
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"
}
}
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"
}
}
}
The card network or brand. Applies to credit, debit, gift, and payment cards.
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"
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"
}
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 |
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 | |
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
| |
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"
}
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.
| ||||||||||||||||||||||||||||||||||
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.
| ||||||||||||||||||||||||||||||||||
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"
}
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
.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.
| ||||||||
payment_type required | string (stored_payment_source_payment_type) [ 1 .. 255 ] characters ^[0-9A-Z_]+$ Indicates the type of the stored payment_source payment.
| ||||||||
usage | string (stored_payment_source_usage_type) [ 1 .. 255 ] characters ^[0-9A-Z_]+$ Default: "DERIVED" Indicates if this is a
| ||||||||
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"
}
}
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"
}
}
}
Type of card. i.e Credit, Debit and so on.
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"
The intent to either capture payment immediately or authorize a payment for an order after order creation.
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 |
"CAPTURE"
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}|[... |