> ## Documentation Index
> Fetch the complete documentation index at: https://docs.paypal.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Authorize payment for order
> 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.
## OpenAPI
````yaml /api-reference/openapi-orders.json post /v2/checkout/orders/{id}/authorize
openapi: 3.0.4
info:
title: Orders
description: >-
An order represents a payment between two or more parties. Use the Orders
API to create, update, retrieve, authorize, and capture orders.
version: '2.32'
servers:
- url: https://api-m.paypal.com
description: Server for https scheme.
security: []
tags:
- name: externalcallback
description: >-
PayPal will use the callback url defined in the create order request to
send merchants shipping address and shipping options data while the buyer
is in the PayPal checkout.
- name: orders
description: >-
Use the `/orders` resource to create, update, retrieve, authorize, capture
and track orders.
- name: trackers
description: >-
Use the `/trackers` resource to update and retrieve tracking information
for PayPal orders.
externalDocs:
url: ../doc/USERGUIDE.md
paths:
/v2/checkout/orders/{id}/authorize:
post:
tags:
- orders
summary: Authorize payment for order
description: >-
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.
operationId: orders.authorize
parameters:
- name: PayPal-Request-Id
description: >-
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. It is
mandatory for all single-step create order calls (E.g. Create Order
Request with payment source information like Card, PayPal.vault_id,
PayPal.billing_agreement_id, etc).
in: header
required: false
schema:
type: string
minLength: 1
maxLength: 108
pattern: ^[\S\s]*$
examples:
authorize_422_payer_action_required_cib_psd2_sca_ba_in_sc:
summary: Authorize Order - 422 - Payer Action Required
description: >-
This code sample attempts to authorize payment for an order that
was created by the api caller and the payment could not be
processed due to PSD2 SCA compliance requirement.
value: 7b92603e-77ed-4896-8e78-5dea2050476a
orders_authorize_idempotent:
summary: Authorize Order - Idempotent Response with PayPal Wallet
description: >-
Authorizes payment for an order with the same idempotency key.
By default, uses the minimal representation.
value: 7b92603e-77ed-4896-8e78-5dea2050476a
authorize_422_unprocessable_entity_payment_denied:
summary: >-
Authorize Order - 422 Unprocessable Entity Error - Payment
Denied
description: >-
This code sample attempts to authorize an order, but the payment
is denied by PayPal. This can occur due to various reasons such
as insufficient funds, expired card, incorrect payment
information, or payment gateway issues.
value: 7b92603e-77ed-4896-8e78-5dea2050476a
00_orders_authorize:
summary: Authorize Order - PayPal Wallet as Payment Source
description: >-
Authorize payment for an order after PayPal wallet approval. By
default, uses the minimal representation.
value: 7b92603e-77ed-4896-8e78-5dea2050476a
orders_authorize_paypal_wallet_vault_id:
summary: Authorize Order - PayPal Wallet Vault ID
description: >-
Authorizes payment for an order through a previously acquired
vault id for a PayPal wallet. By default, uses the minimal
representation.
value: 7b92603e-77ed-4896-8e78-5dea2050476a
- name: Prefer
description: >-
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.
in: header
required: false
schema:
type: string
minLength: 1
maxLength: 25
pattern: ^[a-zA-Z=,-]*$
default: return=minimal
- $ref: '#/components/parameters/paypal_client_metadata_id'
- name: id
description: The ID of the order for which to authorize.
in: path
required: true
schema:
type: string
minLength: 1
maxLength: 36
pattern: ^[A-Z0-9]+$
examples:
00_orders_authorize:
summary: Authorize Order - PayPal Wallet as Payment Source
description: >-
Authorize payment for an order after PayPal wallet approval. By
default, uses the minimal representation.
value: 5O190127TN364715T
authorize_422_payer_action_required_cib_psd2_sca_ba_in_sc:
summary: Authorize Order - 422 - Payer Action Required
description: >-
This code sample attempts to authorize payment for an order that
was created by the api caller and the payment could not be
processed due to PSD2 SCA compliance requirement.
value: 9SY02093A2309081P
authorize_422_unprocessable_entity_payment_denied:
summary: >-
Authorize Order - 422 Unprocessable Entity Error - Payment
Denied
description: >-
This code sample attempts to authorize an order, but the payment
is denied by PayPal. This can occur due to various reasons such
as insufficient funds, expired card, incorrect payment
information, or payment gateway issues.
value: 5O190127TN364715T
orders_authorize_idempotent:
summary: Authorize Order - Idempotent Response with PayPal Wallet
description: >-
Authorizes payment for an order with the same idempotency key.
By default, uses the minimal representation.
value: 5O190127TN364715T
orders_authorize_paypal_wallet_vault_id:
summary: Authorize Order - PayPal Wallet Vault ID
description: >-
Authorizes payment for an order through a previously acquired
vault id for a PayPal wallet. By default, uses the minimal
representation.
value: 5O190127TN364715T
- $ref: '#/components/parameters/authorization'
- $ref: '#/components/parameters/paypal_auth_assertion'
requestBody:
required: false
content:
application/json:
schema:
$ref: '#/components/schemas/order_authorize_request'
examples:
00_orders_authorize:
summary: Authorize Order - PayPal Wallet as Payment Source
description: >-
Authorize payment for an order after PayPal wallet approval.
By default, uses the minimal representation.
value: {}
authorize_422_payer_action_required_cib_psd2_sca_ba_in_sc:
summary: Authorize Order - 422 - Payer Action Required
description: >-
This code sample attempts to authorize payment for an order
that was created by the api caller and the payment could not
be processed due to PSD2 SCA compliance requirement.
value: {}
authorize_422_unprocessable_entity_payment_denied:
summary: >-
Authorize Order - 422 Unprocessable Entity Error - Payment
Denied
description: >-
This code sample attempts to authorize an order, but the
payment is denied by PayPal. This can occur due to various
reasons such as insufficient funds, expired card, incorrect
payment information, or payment gateway issues.
value:
payment_source:
card:
vault_id: 8cg02452we902502k
orders_authorize_idempotent:
summary: Authorize Order - Idempotent Response with PayPal Wallet
description: >-
Authorizes payment for an order with the same idempotency key.
By default, uses the minimal representation.
value: {}
orders_authorize_paypal_wallet_vault_id:
summary: Authorize Order - PayPal Wallet Vault ID
description: >-
Authorizes payment for an order through a previously acquired
vault id for a PayPal wallet. By default, uses the minimal
representation.
value:
payment_source:
paypal:
vault_id: nkq2y9g
responses:
'200':
description: >-
A successful response to an idempotent request returns the HTTP `200
OK` status code with a JSON response body that shows authorized
payment details.
content:
application/json:
schema:
$ref: '#/components/schemas/order_authorize_response'
examples:
orders_authorize_idempotent:
summary: Authorize Order - Idempotent Response with PayPal Wallet
description: >-
Authorizes payment for an order with the same idempotency
key. By default, uses the minimal representation.
value:
id: 5O190127TN364715T
payment_source:
paypal:
name:
given_name: John
surname: Doe
account_status: VERIFIED
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:
authorizations:
- id: 0AW2184448108334S
status: CREATED
amount:
currency_code: USD
value: '100.00'
seller_protection:
status: ELIGIBLE
dispute_categories:
- ITEM_NOT_RECEIVED
- UNAUTHORIZED_TRANSACTION
expiration_time: '2018-05-01T21:20:49Z'
create_time: '2018-04-01T21:20:49Z'
update_time: '2018-04-01T21:20:49Z'
links:
- href: >-
https://api-m.paypal.com/v2/payments/authorizations/0AW2184448108334S
rel: self
method: GET
- href: >-
https://api-m.paypal.com/v2/payments/authorizations/0AW2184448108334S/capture
rel: capture
method: POST
- href: >-
https://api-m.paypal.com/v2/payments/authorizations/0AW2184448108334S/void
rel: void
method: POST
- href: >-
https://api-m.paypal.com/v2/payments/authorizations/0AW2184448108334S/reauthorize
rel: reauthorize
method: POST
payer:
name:
given_name: John
surname: Doe
email_address: customer@example.com
payer_id: QYR5Z8XDVJNXQ
links:
- href: >-
https://api-m.paypal.com/v2/checkout/orders/5O190127TN364715T
rel: self
method: GET
'201':
description: >-
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.
content:
application/json:
schema:
$ref: '#/components/schemas/order_authorize_response'
examples:
00_orders_authorize:
summary: Authorize Order - PayPal Wallet as Payment Source
description: >-
Authorize payment for an order after PayPal wallet approval.
By default, uses the minimal representation.
value:
id: 5O190127TN364715T
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:
- href: >-
https://api-m.paypal.com/v2/payments/authorizations/5O190127TN364715T
rel: self
method: GET
- href: >-
https://api-m.paypal.com/v2/payments/authorizations/5O190127TN364715T/capture
rel: capture
method: POST
- href: >-
https://api-m.paypal.com/v2/payments/authorizations/5O190127TN364715T/void
rel: void
method: POST
- href: >-
https://api-m.paypal.com/v2/checkout/orders/5O190127TN364715T
rel: up
method: GET
payer:
name:
given_name: John
surname: Doe
email_address: customer@example.com
payer_id: QYR5Z8XDVJNXQ
links:
- href: >-
https://api-m.paypal.com/v2/checkout/orders/5O190127TN364715T
rel: self
method: GET
orders_authorize_paypal_wallet_vault_id:
summary: Authorize Order - PayPal Wallet Vault ID
description: >-
Authorizes payment for an order through a previously
acquired vault id for a PayPal wallet. By default, uses the
minimal representation.
value:
id: 5O190127TN364715T
payment_source:
paypal:
name:
given_name: John
surname: Doe
email_address: customer@example.com
account_id: QYR5Z8XDVJNXQ
account_status: VERIFIED
purchase_units:
- reference_id: d9f80740-38f0-11e8-b467-0ed5f89f718b
shipping:
address:
address_line_1: 2211 N First Street
address_line_2: Building 17
admin_area_2: San Jose
admin_area_1: CA
postal_code: '95131'
country_code: US
payments:
authorizations:
- id: 0AW2184448108334S
status: CREATED
amount:
currency_code: USD
value: '100.00'
seller_protection:
status: ELIGIBLE
dispute_categories:
- ITEM_NOT_RECEIVED
- UNAUTHORIZED_TRANSACTION
expiration_time: '2022-01-29T21:20:49Z'
create_time: '2021-12-29T21:20:49Z'
update_time: '2021-12-29T21:20:49Z'
links:
- href: >-
https://api-m.paypal.com/v2/payments/authorizations/0AW2184448108334S
rel: self
method: GET
- href: >-
https://api-m.paypal.com/v2/payments/authorizations/0AW2184448108334S/capture
rel: capture
method: POST
- href: >-
https://api-m.paypal.com/v2/payments/authorizations/0AW2184448108334S/void
rel: void
method: POST
- href: >-
https://api-m.paypal.com/v2/payments/authorizations/0AW2184448108334S/reauthorize
rel: reauthorize
method: POST
links:
- href: >-
https://api-m.paypal.com/v2/checkout/orders/5O190127TN364715T
rel: self
method: GET
'202':
description: >-
The request has been accepted for processing, but the processing has
not been completed yet. The server returns the HTTP `202 Accepted`
status code to indicate that the request is valid and will be
handled asynchronously.
content:
application/json:
schema:
$ref: '#/components/schemas/order_authorize_response'
'207':
description: >-
The request was successfully processed, but the result contains
mixed outcomes. When an order includes multiple purchase units, the
server returns the HTTP `207 Multi-Status` code to indicate that one
or more purchase units were processed successfully while others
failed. The response body provides the processing result for each
purchase unit.
content:
application/json:
schema:
$ref: '#/components/schemas/order_authorize_response'
'400':
description: >-
Request is not well-formed, syntactically incorrect, or violates
schema.
content:
application/json:
schema:
$ref: '#/components/schemas/error'
'401':
$ref: '#/components/responses/401_error_response'
'403':
$ref: '#/components/responses/403_error_response'
'404':
$ref: '#/components/responses/404_error_response'
'409':
description: >-
The request could not be completed due to a conflict with the
current state of the resource. The HTTP `409 Conflict` status code
is returned when the requested operation is not allowed because the
order or one or more purchase units are in a state that prevents the
operation.
content:
application/json:
schema:
$ref: '#/components/schemas/error'
'422':
description: >-
The requested action could not be performed, semantically incorrect,
or failed business validation.
content:
application/json:
schema:
$ref: '#/components/schemas/error'
examples:
authorize_422_payer_action_required_cib_psd2_sca_ba_in_sc:
summary: Authorize Order - 422 - Payer Action Required
description: >-
This code sample attempts to authorize payment for an order
that was created by the api caller and the payment could not
be processed due to PSD2 SCA compliance requirement.
value:
name: UNPROCESSABLE_ENTITY
details:
- issue: PAYER_ACTION_REQUIRED
description: >-
Transaction cannot complete successfully, instruct the
buyer to return to PayPal.
message: >-
The requested action could not be performed, semantically
incorrect, or failed business validation.
debug_id: f63fbc340a6ce
links:
- href: >-
https://developer.paypal.com/api/orders/v2/#error-PAYER_ACTION_REQUIRED
rel: information_link
method: GET
- href: >-
https://www.paypal.com/checkoutnow?token=9SY02093A2309081P
rel: payer-action
method: GET
authorize_422_unprocessable_entity_payment_denied:
summary: >-
Authorize Order - 422 Unprocessable Entity Error - Payment
Denied
description: >-
This code sample attempts to authorize an order, but the
payment is denied by PayPal. This can occur due to various
reasons such as insufficient funds, expired card, incorrect
payment information, or payment gateway issues.
value:
name: UNPROCESSABLE_ENTITY
details:
- issue: PAYMENT_DENIED
description: PayPal has declined to process this transaction.
message: >-
The requested action could not be performed, semantically
incorrect, or failed business validation.
debug_id: eb476257836d9
links:
- href: >-
https://developer.paypal.com/docs/api/orders/v2/#error-PAYMENT_DENIED
rel: information_link
method: GET
'500':
$ref: '#/components/responses/500_error_response'
default:
$ref: '#/components/responses/default_response'
security:
- Oauth2:
- https://uri.paypal.com/services/payments/payment
- >-
https://uri.paypal.com/services/payments/orders/deprecating-jssdk-migration-for-limited-merchants
components:
parameters:
paypal_client_metadata_id:
name: PayPal-Client-Metadata-Id
in: header
description: >-
A GUID value originating from Fraudnet and Dyson passed from external
API clients via HTTP header. The value is used by Risk decisions to
correlate calls which, in turn, might result in lower decline rates..
required: false
schema:
$ref: '#/components/schemas/guid'
examples:
guid:
summary: A GUID.
description: A paypal-client-metadata-id header with a randomized value.
value: 1295065d-6f34-42dc-ac65-fac0c86af250
authorization:
name: Authorization
in: header
description: Holds authorization information for external API calls.
required: false
schema:
$ref: '#/components/schemas/standard_header_schema'
examples:
bearer:
summary: Bearer authorization.
description: >-
An authorization header with information for the Bearer
authorization scheme. The authorization parameter value is
randomized for this example.
value: >-
Bearer
A21AAGHr9qtiRRXH4oYcQokQgV99rGqEIfgrr8xHCclP0OzmD9KVgg5ppIIg1jzJgQkV4wd02svIvBJyg6cLFJjFow_SjBhxQ
paypal_auth_assertion:
name: PayPal-Auth-Assertion
in: header
description: >-
Header for an API client-provided JWT assertion that identifies the
merchant. Establishing the consent to act-on-behalf of a merchant is a
prerequisite for using this header.
required: false
schema:
description: >-
Header for an API client-provided JWT assertion that identifies the
merchant. Establishing the consent to act-on-behalf of a merchant is a
prerequisite for using this header.
type: string
minLength: 1
maxLength: 10000
pattern: ^.*$
examples:
auth_assertion:
summary: An auth assertion.
description: A paypal-auth-assertion header with a randomized value.
value: eyJhbGciOiJub25lIn0.eyJlbWFpbCI6Im15QGVtYWlsLmNvbSJ9
schemas:
order_authorize_request:
title: Order Authorize Request
description: The authorization of an order request.
type: object
properties:
payment_source:
allOf:
- $ref: '#/components/schemas/payment_source'
- description: >-
The source of payment for the order, which can be a token or a
card. Use this object only if you have not redirected the user
after order creation to approve the payment. In such cases, the
user-selected payment method in the PayPal flow is implicitly
used.
order_authorize_response:
title: Order Authorize Response
description: The order authorize response.
type: object
allOf:
- allOf:
- $ref: '#/components/schemas/activity_timestamps'
- title: activity_timestamps
- type: object
title: Order Authorize Response
description: The order authorize response.
properties:
id:
description: The ID of the order.
type: string
minLength: 0
maxLength: 2147483647
pattern: ^[\S\s]*$
readOnly: true
payment_source:
allOf:
- $ref: '#/components/schemas/payment_source_response'
- not:
anyOf:
- required:
- alipay
- required:
- bancomatpay
- required:
- bancontact
- required:
- blik
- required:
- boletobancario
- required:
- eps
- required:
- giropay
- required:
- grabpay
- required:
- ideal
- required:
- mbway
- required:
- multibanco
- required:
- mybank
- required:
- oxxo
- required:
- payu
- required:
- pay_upon_invoice
- required:
- p24
- required:
- safetypay
- required:
- satispay
- required:
- swish
- required:
- sofort
- required:
- trustly
- required:
- verkkopankki
- required:
- wechatpay
intent:
allOf:
- $ref: '#/components/schemas/checkout_payment_intent'
payer:
allOf:
- $ref: '#/components/schemas/payer'
purchase_units:
description: >-
An array of purchase units. Each purchase unit establishes a
contract between a customer and merchant. Each purchase unit
represents either a full or partial order that the customer
intends to purchase from the merchant.
type: array
minItems: 1
maxItems: 10
items:
allOf:
- $ref: '#/components/schemas/purchase_unit'
- title: purchase_unit
description: >-
A purchase unit. Establishes a contract between a customer
and merchant.
status:
allOf:
- $ref: '#/components/schemas/order_status'
- readOnly: true
links:
description: >-
An array of request-related HATEOAS links. To complete payer
approval, use the `approve` link to redirect the payer. The API
caller has 6 hours (default setting, this which can be changed
by your account manager to 24/48/72 hours to accommodate your
use case) from the time the order is created, to redirect your
payer. Once redirected, the API caller has 6 hours for the payer
to approve the order and either authorize or capture the order.
If you are not using the PayPal JavaScript SDK to initiate
PayPal Checkout (in context) ensure that you include
`application_context.return_url` is specified or you will get
"We're sorry, Things don't appear to be working at the moment"
after the payer approves the payment.
type: array
minItems: 0
maxItems: 32767
readOnly: true
items:
allOf:
- $ref: '#/components/schemas/link_description-2'
- title: link_description
description: >-
A request-related [HATEOAS
link](/api/rest/responses/#hateoas-links). To complete
payer approval, use the `approve` link with the `GET`
method.
error:
title: Error
description: The error details.
type: object
required:
- debug_id
- message
- name
properties:
name:
description: The human-readable, unique name of the error.
type: string
minLength: 0
maxLength: 2147483647
pattern: ^[\S\s]*$
message:
description: The message that describes the error.
type: string
minLength: 0
maxLength: 2147483647
pattern: ^[\S\s]*$
debug_id:
description: The PayPal internal ID. Used for correlation purposes.
type: string
minLength: 0
maxLength: 2147483647
pattern: ^[\S\s]*$
details:
description: An array of additional details about the error.
type: array
minItems: 0
maxItems: 32767
items:
allOf:
- $ref: '#/components/schemas/error_details'
- title: error_details
links:
description: >-
An array of request-related [HATEOAS
links](/api/rest/responses/#hateoas-links).
type: array
minItems: 0
maxItems: 32767
readOnly: true
items:
allOf:
- $ref: '#/components/schemas/link_description'
- title: link_description
readOnly: true
guid:
title: GUID
description: A Globally Unique Identifier (GUID) value.
type: string
minLength: 1
maxLength: 68
pattern: ^[A-Za-z0-9-{}(),]*$
standard_header_schema:
title: Schema Object for standard headers
description: >-
Standard headers are generally less restrictive in structure due to
historical precedent across browsers, etc. This is a common schema for
use in defining most standard headers.
type: string
minLength: 1
maxLength: 16000
pattern: ^.*$
payment_source:
title: payment_source
description: The payment source definition.
type: object
properties:
card:
$ref: '#/components/schemas/card_request'
token:
$ref: '#/components/schemas/token'
paypal:
allOf:
- $ref: '#/components/schemas/paypal_wallet'
- description: >-
Indicates that PayPal Wallet is the payment source. Main use of
this selection is to provide additional instructions associated
with this choice like vaulting.
bancontact:
allOf:
- $ref: '#/components/schemas/bancontact_request'
- title: bancontact
description: >-
Bancontact is the most popular online payment in Belgium. [More
Details](https://www.bancontact.com/).
blik:
allOf:
- $ref: '#/components/schemas/blik_request'
- title: blik
description: >-
BLIK is a mobile payment system, created by Polish Payment
Standard in order to allow millions of users to pay in shops,
payout cash in ATMs and make online purchases and payments.
[More Details](https://blikmobile.pl/).
eps:
allOf:
- $ref: '#/components/schemas/eps_request'
- title: eps
description: >-
The eps transfer is an online payment method developed by many
Austrian banks. [More
Details](https://www.eps-ueberweisung.at/).
giropay:
allOf:
- $ref: '#/components/schemas/giropay_request'
- title: giropay
description: >-
Giropay is an Internet payment System in Germany, based on
online banking. [More Details](https://giropay.de/).
ideal:
allOf:
- $ref: '#/components/schemas/ideal_request'
- title: ideal
description: >-
The Dutch payment method iDEAL is an online payment method that
enables consumers to pay online through their own bank. [More
Details](https://www.ideal.nl/).
mybank:
allOf:
- $ref: '#/components/schemas/mybank_request'
- title: mybank
description: >-
MyBank is an e-authorisation solution which enables safe digital
payments and identity authentication through a consumer’s own
online banking portal or mobile application. [More
Details](https://www.mybank.eu/).
p24:
allOf:
- $ref: '#/components/schemas/p24_request'
- title: p24
description: >-
P24 (Przelewy24) is a secure and fast online bank transfer
service linked to all the major banks in Poland. [More
Details](https://www.przelewy24.pl/).
sofort:
allOf:
- $ref: '#/components/schemas/sofort_request'
- title: sofort
description: >-
SOFORT Banking is a real-time bank transfer payment method that
buyers use to transfer funds directly to merchants from their
bank accounts. [More Details](https://www.klarna.com/sofort/).
trustly:
allOf:
- $ref: '#/components/schemas/trustly_request'
- title: trustly
description: >-
Trustly is a payment method that allows customers to shop and
pay from their bank account. [More
Details](https://www.trustly.net/).
apple_pay:
allOf:
- $ref: '#/components/schemas/apple_pay_request'
- title: applepay
description: >-
ApplePay payment source, allows buyer to pay using ApplePay,
both on Web as well as on Native.
google_pay:
allOf:
- $ref: '#/components/schemas/google_pay_request'
- title: googlepay
description: Google Pay payment source, allows buyer to pay using Google Pay.
venmo:
allOf:
- $ref: '#/components/schemas/venmo_wallet_request'
- title: venmo
description: >-
Information needed to indicate that Venmo is being used to fund
the payment.
crypto:
allOf:
- $ref: '#/components/schemas/crypto_request'
- title: crypto
description: Indicates that Crypto Wallet is the payment source.
activity_timestamps:
title: activity_timestamps
description: >-
The date and time stamps that are common to authorized payment, captured
payment, and refund transactions.
type: object
properties:
create_time:
allOf:
- $ref: '#/components/schemas/date_time'
- description: >-
The date and time when the transaction occurred, in [Internet
date and time
format](https://tools.ietf.org/html/rfc3339#section-5.6).
readOnly: true
update_time:
allOf:
- $ref: '#/components/schemas/date_time'
- description: >-
The date and time when the transaction was last updated, in
[Internet date and time
format](https://tools.ietf.org/html/rfc3339#section-5.6).
readOnly: true
payment_source_response:
title: payment_source_response
description: The payment source used to fund the payment.
type: object
properties:
card:
$ref: '#/components/schemas/card_response'
paypal:
$ref: '#/components/schemas/paypal_wallet_response'
bancontact:
$ref: '#/components/schemas/bancontact'
blik:
$ref: '#/components/schemas/blik'
eps:
$ref: '#/components/schemas/eps'
giropay:
$ref: '#/components/schemas/giropay'
ideal:
$ref: '#/components/schemas/ideal'
mybank:
$ref: '#/components/schemas/mybank'
p24:
$ref: '#/components/schemas/p24'
sofort:
$ref: '#/components/schemas/sofort'
trustly:
$ref: '#/components/schemas/trustly'
apple_pay:
$ref: '#/components/schemas/apple_pay'
google_pay:
$ref: '#/components/schemas/google_pay'
venmo:
$ref: '#/components/schemas/venmo_wallet_response'
crypto:
$ref: '#/components/schemas/crypto'
checkout_payment_intent:
title: checkout_payment_intent
description: >-
The intent to either capture payment immediately or authorize a payment
for an order after order creation.
type: string
enum:
- CAPTURE
- AUTHORIZE
payer:
title: payer
description: >-
The customer who approves and pays for the order. The customer is also
known as the payer.
type: object
allOf:
- $ref: '#/components/schemas/payer_base'
- type: object
properties:
name:
allOf:
- $ref: '#/components/schemas/name'
- description: >-
The name of the payer. Supports only the `given_name` and
`surname` properties.
not:
anyOf:
- required:
- prefix
- required:
- middle_name
- required:
- suffix
- required:
- alternate_full_name
- required:
- full_name
phone:
allOf:
- $ref: '#/components/schemas/phone_with_type'
- description: >-
The phone number of the customer. Available only when you
enable the **Contact Telephone Number** option in the **Profile
& Settings** for the merchant's PayPal account. The
`phone.phone_number` supports only `national_number`.
birth_date:
allOf:
- $ref: '#/components/schemas/date_no_time'
- description: The birth date of the payer in `YYYY-MM-DD` format.
tax_info:
allOf:
- $ref: '#/components/schemas/tax_info'
- description: >-
The tax information of the payer. Required only for
Brazilian payer's. Both `tax_id` and `tax_id_type` are
required.
address:
allOf:
- $ref: '#/components/schemas/address_portable'
- description: >-
The address of the payer. Supports only the
`address_line_1`, `address_line_2`, `admin_area_1`,
`admin_area_2`, `postal_code`, and `country_code`
properties. Also referred to as the billing address of the
customer.
not:
anyOf:
- required:
- address_line_3
- required:
- admin_area_3
- required:
- admin_area_4
- required:
- address_details
purchase_unit:
title: Purchase Unit
description: >-
The purchase unit details. Used to capture required information for the
payment contract.
type: object
properties:
reference_id:
description: >-
The API caller-provided external ID for the purchase unit. Required
for multiple purchase units when you must update the order through
`PATCH`. If you omit this value and the order contains only one
purchase unit, PayPal sets this value to `default`.
Note: If there are multiple purchase
units, reference_id is required for each purchase
unit.
type: string
minLength: 1
maxLength: 256
pattern: ^[\S\s]*$
amount:
$ref: '#/components/schemas/amount_with_breakdown'
payee:
allOf:
- $ref: '#/components/schemas/payee'
- description: The merchant who receives payment for this transaction.
payment_instruction:
$ref: '#/components/schemas/payment_instruction'
description:
description: The purchase description.
type: string
minLength: 1
maxLength: 127
pattern: ^[\S\s]*$
custom_id:
description: >-
The API caller-provided external ID. Used to reconcile API
caller-initiated transactions with PayPal transactions. Appears in
transaction and settlement reports.
type: string
minLength: 1
maxLength: 255
pattern: ^[\S\s]*$
invoice_id:
description: The API caller-provided external invoice ID for this order.
type: string
minLength: 1
maxLength: 127
pattern: ^[\S\s]*$
id:
description: >-
The PayPal-generated ID for the purchase unit. This ID appears in
both the payer's transaction history and the emails that the payer
receives. In addition, this ID is available in transaction and
settlement reports that merchants and API callers can use to
reconcile transactions. This ID is only available when an order is
saved by calling v2/checkout/orders/id/save.
type: string
minLength: 1
maxLength: 19
pattern: ^[\S\s]*$
soft_descriptor:
description: >-
The payment descriptor on account transactions on the customer's
credit card statement, that PayPal sends to processors. The maximum
length of the soft descriptor information that you can pass in the
API field is 22 characters, in the following format:22 -
len(PAYPAL * (8)) - len(Descriptor in Payment Receiving
Preferences of Merchant account + 1)The PAYPAL prefix
uses 8 characters.
The soft descriptor supports the
following ASCII characters:- Alphanumeric
characters
- Dashes
- Asterisks
- Periods
(.)
- Spaces
For Wallet payments marketplace
integrations:- The merchant descriptor in the Payment
Receiving Preferences must be the marketplace name.
- You
can't use the remaining space to show the customer service
number.
- The remaining spaces can be a combination of seller
name and country.
For unbranded payments (Direct Card)
marketplace integrations, use a combination of the seller name and
phone number.
type: string
minLength: 1
maxLength: 22
pattern: ^[\S\s]*$
items:
description: An array of items that the customer purchases from the merchant.
type: array
minItems: 0
maxItems: 32767
items:
allOf:
- $ref: '#/components/schemas/item'
- title: item
description: An item.
shipping:
allOf:
- $ref: '#/components/schemas/shipping_with_tracking_details'
- description: The shipping address and method.
supplementary_data:
allOf:
- $ref: '#/components/schemas/supplementary_data'
- description: >-
Supplementary data about this payment. 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.
payments:
allOf:
- $ref: '#/components/schemas/payment_collection'
- description: The comprehensive history of payments for the purchase unit.
readOnly: true
order_status:
title: Order Status
description: The order status.
type: string
enum:
- CREATED
- SAVED
- APPROVED
- VOIDED
- COMPLETED
- PAYER_ACTION_REQUIRED
link_description-2:
title: Link Description
description: >-
The request-related [HATEOAS link](/api/rest/responses/#hateoas-links)
information.
type: object
required:
- href
- rel
properties:
href:
description: >-
The complete target URL. To make the related call, combine the
method with this [URI
Template-formatted](https://tools.ietf.org/html/rfc6570) link. For
pre-processing, include the `$`, `(`, and `)` characters. The `href`
is the key HATEOAS component that links a completed call with a
subsequent call.
type: string
minLength: 0
maxLength: 2147483647
pattern: ^[\S\s]*$
rel:
description: >-
The [link relation
type](https://tools.ietf.org/html/rfc5988#section-4), which serves
as an ID for a link that unambiguously describes the semantics of
the link. See [Link
Relations](https://www.iana.org/assignments/link-relations/link-relations.xhtml).
type: string
minLength: 0
maxLength: 2147483647
pattern: ^[\S\s]*$
method:
description: The HTTP method required to make the related call.
type: string
enum:
- GET
- POST
- PUT
- DELETE
- HEAD
- CONNECT
- OPTIONS
- PATCH
title:
description: The link title.
type: string
minLength: 0
maxLength: 2147483647
pattern: ^[\S\s]*$
mediaType:
title: media_type
description: >-
The media type, as defined by [RFC
2046](https://www.ietf.org/rfc/rfc2046.txt). Describes the link
target.
type: string
minLength: 0
maxLength: 2147483647
pattern: ^[\S\s]*$
encType:
title: enc_type
description: The media type in which to submit the request data.
type: string
minLength: 0
maxLength: 2147483647
pattern: ^[\S\s]*$
default: application/json
schema:
allOf:
- $ref: '#/components/schemas/link_schema-2'
- description: The schema that describes the request data.
targetSchema:
allOf:
- $ref: '#/components/schemas/link_schema-2'
- title: target_schema
description: The schema that describes the link target.
error_details:
title: Error Details
description: The error details. Required for client-side `4XX` errors.
type: object
required:
- issue
properties:
field:
description: >-
The field that caused the error. If this field is in the body, set
this value to the field's JSON pointer value. Required for
client-side errors.
type: string
minLength: 0
maxLength: 2147483647
pattern: ^[\S\s]*$
value:
description: The value of the field that caused the error.
type: string
minLength: 0
maxLength: 2147483647
pattern: ^[\S\s]*$
location:
description: >-
The location of the field that caused the error. Value is `body`,
`path`, or `query`.
type: string
minLength: 0
maxLength: 2147483647
pattern: ^[\S\s]*$
default: body
issue:
description: The unique, fine-grained application-level error code.
type: string
minLength: 0
maxLength: 2147483647
pattern: ^[\S\s]*$
links:
description: >-
An array of request-related [HATEOAS
links](/api/rest/responses/#hateoas-links) that are either relevant
to the issue by providing additional information or offering
potential resolutions.
type: array
minItems: 1
maxItems: 4
readOnly: true
items:
allOf:
- $ref: '#/components/schemas/link_description'
- title: link_description
readOnly: true
description:
description: >-
The human-readable description for an issue. The description can
change over the lifetime of an API, so clients must not depend on
this value.
type: string
minLength: 0
maxLength: 2147483647
pattern: ^[\S\s]*$
link_description:
title: Link Description
description: >-
The request-related [HATEOAS link](/api/rest/responses/#hateoas-links)
information.
type: object
required:
- href
- rel
properties:
href:
description: >-
The complete target URL. To make the related call, combine the
method with this [URI
Template-formatted](https://tools.ietf.org/html/rfc6570) link. For
pre-processing, include the `$`, `(`, and `)` characters. The `href`
is the key HATEOAS component that links a completed call with a
subsequent call.
type: string
minLength: 0
maxLength: 2147483647
pattern: ^[\S\s]*$
rel:
description: >-
The [link relation
type](https://tools.ietf.org/html/rfc5988#section-4), which serves
as an ID for a link that unambiguously describes the semantics of
the link. See [Link
Relations](https://www.iana.org/assignments/link-relations/link-relations.xhtml).
type: string
minLength: 0
maxLength: 2147483647
pattern: ^[\S\s]*$
method:
description: The HTTP method required to make the related call.
type: string
enum:
- GET
- POST
- PUT
- DELETE
- HEAD
- CONNECT
- OPTIONS
- PATCH
title:
description: The link title.
type: string
minLength: 0
maxLength: 2147483647
pattern: ^[\S\s]*$
mediaType:
title: media_type
description: >-
The media type, as defined by [RFC
2046](https://www.ietf.org/rfc/rfc2046.txt). Describes the link
target.
type: string
minLength: 0
maxLength: 2147483647
pattern: ^[\S\s]*$
encType:
title: enc_type
description: The media type in which to submit the request data.
type: string
minLength: 0
maxLength: 2147483647
pattern: ^[\S\s]*$
default: application/json
schema:
allOf:
- $ref: '#/components/schemas/link_schema'
- description: The schema that describes the request data.
targetSchema:
allOf:
- $ref: '#/components/schemas/link_schema'
- title: target_schema
description: The schema that describes the link target.
card_request:
title: card_request
description: >-
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*.
type: object
allOf:
- allOf:
- $ref: '#/components/schemas/card'
- not:
anyOf:
- required:
- id
- required:
- last_digits
- required:
- card_type
- required:
- type
- required:
- brand
- type: object
properties:
vault_id:
allOf:
- $ref: '#/components/schemas/vault_id'
- description: >-
The PayPal-generated ID for the saved card payment source.
Typically stored on the merchant's server.
single_use_token:
allOf:
- $ref: '#/components/schemas/single_use_token'
- description: >-
The PayPal-generated, short-lived, one-time-use token, used
to communicate payment information to PayPal for transaction
processing.
stored_credential:
$ref: '#/components/schemas/card_stored_credential'
network_token:
allOf:
- $ref: '#/components/schemas/network_token_request'
- description: >-
A 3rd party network token refers to a network token that the
merchant provisions from and vaults with an external TSP
(Token Service Provider) other than PayPal.
experience_context:
allOf:
- $ref: '#/components/schemas/card_experience_context'
- {}
token:
title: token
description: The tokenized payment source to fund a payment.
type: object
required:
- id
- type
properties:
id:
description: The PayPal-generated ID for the token.
type: string
minLength: 1
maxLength: 255
pattern: ^[0-9a-zA-Z_-]+$
type:
description: The tokenization method that generated the ID.
type: string
enum:
- BILLING_AGREEMENT
paypal_wallet:
title: paypal_wallet
description: A resource that identifies a PayPal Wallet is used for payment.
type: object
properties:
vault_id:
allOf:
- $ref: '#/components/schemas/vault_id'
- description: >-
The PayPal-generated ID for the payment_source stored within the
Vault.
email_address:
allOf:
- $ref: '#/components/schemas/email'
- description: The email address of the PayPal account holder.
name:
allOf:
- $ref: '#/components/schemas/name'
- description: >-
The name of the PayPal account holder. Supports only the
`given_name` and `surname` properties.
not:
anyOf:
- required:
- prefix
- required:
- middle_name
- required:
- suffix
- required:
- alternate_full_name
- required:
- full_name
phone:
allOf:
- $ref: '#/components/schemas/phone_with_type'
- description: >-
The phone number of the customer. Available only when you enable
the **Contact Telephone Number** option in the **Profile
& Settings** for the merchant's PayPal account. The
`phone.phone_number` supports only `national_number`.
birth_date:
allOf:
- $ref: '#/components/schemas/date_no_time'
- description: >-
The birth date of the PayPal account holder in `YYYY-MM-DD`
format.
tax_info:
allOf:
- $ref: '#/components/schemas/tax_info'
- description: >-
The tax information of the PayPal account holder. Required only
for Brazilian PayPal account holder's. Both `tax_id` and
`tax_id_type` are required.
address:
allOf:
- $ref: '#/components/schemas/address_portable'
- description: >-
The address of the PayPal account holder. Supports only the
`address_line_1`, `address_line_2`, `admin_area_1`,
`admin_area_2`, `postal_code`, and `country_code` properties.
Also referred to as the billing address of the customer.
not:
anyOf:
- required:
- address_line_3
- required:
- admin_area_3
- required:
- admin_area_4
- required:
- address_details
attributes:
allOf:
- $ref: '#/components/schemas/paypal_wallet_attributes'
- title: paypal_wallet_attributes
description: Additional attributes associated with the use of this wallet.
experience_context:
$ref: '#/components/schemas/paypal_wallet_experience_context'
billing_agreement_id:
$ref: '#/components/schemas/billing_agreement_id'
stored_credential:
$ref: '#/components/schemas/paypal_wallet_stored_credential'
bancontact_request:
title: bancontact_request
description: Information needed to pay using Bancontact.
type: object
required:
- country_code
- name
properties:
name:
allOf:
- $ref: '#/components/schemas/full_name'
- title: name
description: >-
The name of the account holder associated with this payment
method.
country_code:
allOf:
- $ref: '#/components/schemas/country_code-2'
- description: The two-character ISO 3166-1 country code.
experience_context:
allOf:
- $ref: '#/components/schemas/experience_context_base'
- description: >-
Customizes the payer experience during the approval process for
the payment.
blik_request:
title: blik_request
description: Information needed to pay using BLIK.
type: object
required:
- country_code
- name
properties:
name:
allOf:
- $ref: '#/components/schemas/full_name'
- title: name
description: >-
The name of the account holder associated with this payment
method.
country_code:
allOf:
- $ref: '#/components/schemas/country_code-2'
- description: The two-character ISO 3166-1 country code.
email:
allOf:
- $ref: '#/components/schemas/email_address'
- description: >-
The email address of the account holder associated with this
payment method.
experience_context:
allOf:
- $ref: '#/components/schemas/blik_experience_context'
- description: >-
Customizes the payer experience during the approval process for
the payment.
level_0:
allOf:
- $ref: '#/components/schemas/blik_seamless'
- description: The level_0 integration flow object.
one_click:
allOf:
- $ref: '#/components/schemas/blik_one_click'
- description: The one-click integration flow object.
eps_request:
title: eps_request
description: Information needed to pay using eps.
type: object
required:
- country_code
- name
properties:
name:
allOf:
- $ref: '#/components/schemas/full_name'
- title: name
description: >-
The name of the account holder associated with this payment
method.
country_code:
allOf:
- $ref: '#/components/schemas/country_code-2'
- description: The two-character ISO 3166-1 country code.
experience_context:
allOf:
- $ref: '#/components/schemas/experience_context_base'
- description: >-
Customizes the payer experience during the approval process for
the payment.
giropay_request:
title: giropay_request
description: Information needed to pay using giropay.
type: object
required:
- country_code
- name
properties:
name:
allOf:
- $ref: '#/components/schemas/full_name'
- title: name
description: >-
The name of the account holder associated with this payment
method.
country_code:
allOf:
- $ref: '#/components/schemas/country_code-2'
- description: The two-character ISO 3166-1 country code.
experience_context:
allOf:
- $ref: '#/components/schemas/experience_context_base'
- description: >-
Customizes the payer experience during the approval process for
the payment.
ideal_request:
title: ideal_request
description: Information needed to pay using iDEAL.
type: object
required:
- country_code
- name
properties:
name:
allOf:
- $ref: '#/components/schemas/full_name'
- title: name
description: >-
The name of the account holder associated with this payment
method.
country_code:
allOf:
- $ref: '#/components/schemas/country_code-2'
- description: The two-character ISO 3166-1 country code.
bic:
allOf:
- $ref: '#/components/schemas/bic'
- description: The bank identification code (BIC).
experience_context:
allOf:
- $ref: '#/components/schemas/experience_context_base'
- description: >-
Customizes the payer experience during the approval process for
the payment.
mybank_request:
title: mybank_request
description: Information needed to pay using MyBank.
type: object
required:
- country_code
- name
properties:
name:
allOf:
- $ref: '#/components/schemas/full_name'
- title: name
description: >-
The name of the account holder associated with this payment
method.
country_code:
allOf:
- $ref: '#/components/schemas/country_code-2'
- description: The two-character ISO 3166-1 country code.
experience_context:
allOf:
- $ref: '#/components/schemas/experience_context_base'
- description: >-
Customizes the payer experience during the approval process for
the payment.
p24_request:
title: p24_request
description: Information needed to pay using P24 (Przelewy24).
type: object
required:
- country_code
- email
- name
properties:
name:
allOf:
- $ref: '#/components/schemas/full_name'
- title: name
description: >-
The name of the account holder associated with this payment
method.
email:
allOf:
- $ref: '#/components/schemas/email_address'
- description: >-
The email address of the account holder associated with this
payment method.
country_code:
allOf:
- $ref: '#/components/schemas/country_code-2'
- description: The two-character ISO 3166-1 country code.
experience_context:
allOf:
- $ref: '#/components/schemas/experience_context_base'
- description: >-
Customizes the payer experience during the approval process for
the payment.
sofort_request:
title: sofort_request
description: Information needed to pay using Sofort.
type: object
required:
- country_code
- name
properties:
name:
allOf:
- $ref: '#/components/schemas/full_name'
- title: name
description: >-
The name of the account holder associated with this payment
method.
country_code:
allOf:
- $ref: '#/components/schemas/country_code-2'
- description: The two-character ISO 3166-1 country code.
experience_context:
allOf:
- $ref: '#/components/schemas/experience_context_base'
- description: >-
Customizes the payer experience during the approval process for
the payment.
trustly_request:
title: trustly_request
description: Information needed to pay using Trustly.
type: object
required:
- country_code
- email
- name
properties:
name:
allOf:
- $ref: '#/components/schemas/full_name'
- title: name
description: >-
The name of the account holder associated with this payment
method.
country_code:
allOf:
- $ref: '#/components/schemas/country_code-2'
- description: The two-character ISO 3166-1 country code.
email:
allOf:
- $ref: '#/components/schemas/email_address'
- description: >-
The email address of the account holder associated with this
payment method.
experience_context:
allOf:
- $ref: '#/components/schemas/experience_context_base'
- description: >-
Customizes the payer experience during the approval process for
the payment.
apple_pay_request:
title: apple_pay_request
description: Information needed to pay using ApplePay.
type: object
properties:
id:
description: >-
ApplePay transaction identifier, this will be the unique identifier
for this transaction provided by Apple. The pattern is defined by an
external party and supports Unicode.
type: string
minLength: 1
maxLength: 250
pattern: ^.*$
name:
allOf:
- $ref: '#/components/schemas/full_name'
- description: Name on the account holder associated with apple pay.
email_address:
allOf:
- $ref: '#/components/schemas/email_address'
- description: >-
The email address of the account holder associated with apple
pay.
phone_number:
allOf:
- $ref: '#/components/schemas/phone_number_without_country_code'
- description: >-
The phone number, in its canonical international [E.164
numbering plan format](https://www.itu.int/rec/T-REC-E.164/en).
Supports only the `national_number` property.
decrypted_token:
allOf:
- $ref: '#/components/schemas/apple_pay_decrypted_token_data'
- description: The decrypted payload details for the apple pay token.
stored_credential:
$ref: '#/components/schemas/card_stored_credential'
vault_id:
allOf:
- $ref: '#/components/schemas/vault_id'
- description: >-
The PayPal-generated ID for the saved apple pay payment_source.
This ID should be stored on the merchant's server so the saved
payment source can be used for future transactions.
attributes:
$ref: '#/components/schemas/apple_pay_attributes'
experience_context:
$ref: '#/components/schemas/apple_pay_experience_context'
google_pay_request:
title: google_pay_request
description: Information needed to pay using Google Pay.
type: object
properties:
name:
allOf:
- $ref: '#/components/schemas/full_name'
- description: Name on the account holder associated with Google Pay.
email_address:
allOf:
- $ref: '#/components/schemas/email_address'
- description: >-
The email address of the account holder associated with Google
Pay.
phone_number:
allOf:
- $ref: >-
#/components/schemas/phone_with_national_required_and_country_code
- description: >-
The phone number of account holder, in its canonical
international [E.164 numbering plan
format](https://www.itu.int/rec/T-REC-E.164/en). Supports only
the `national_number` property.
card:
allOf:
- $ref: '#/components/schemas/google_pay_card'
- description: The payment card information.
not:
anyOf:
- required:
- number
- required:
- expiry
- required:
- last_digits
decrypted_token:
allOf:
- $ref: '#/components/schemas/google_pay_decrypted_token_data'
- description: The decrypted payload details for the Google Pay token.
assurance_details:
allOf:
- $ref: '#/components/schemas/assurance_details'
- description: >-
Information about what validation has been performed on the
returned payment credentials.
experience_context:
$ref: '#/components/schemas/google_pay_experience_context'
venmo_wallet_request:
title: venmo_wallet_request
description: Information needed to pay using Venmo.
type: object
properties:
vault_id:
allOf:
- $ref: '#/components/schemas/vault_id'
- description: >-
The PayPal-generated ID for the saved Venmo wallet
payment_source. This ID should be stored on the merchant's
server so the saved payment source can be used for future
transactions.
email_address:
allOf:
- $ref: '#/components/schemas/email'
- description: The email address of the payer.
experience_context:
$ref: '#/components/schemas/venmo_wallet_experience_context'
attributes:
allOf:
- $ref: '#/components/schemas/venmo_wallet_attributes'
- description: Additional attributes associated with the use of this wallet.
crypto_request:
title: crypto_request
description: Crypto payment used to fund the transaction.
type: object
required:
- country_code
- experience_context
- name
properties:
country_code:
allOf:
- $ref: '#/components/schemas/country_code'
- description: The two-character ISO 3166-1 purchase country code.
name:
allOf:
- $ref: '#/components/schemas/crypto_account_holder_name'
- description: The name of the account holder associated with Crypto wallet.
experience_context:
allOf:
- $ref: >-
#/components/schemas/experience_context_base_without_brand_shipping
- description: >-
Customizes the payer experience during the approval process for
the payment.
date_time:
description: >-
The date and time, in [Internet date and time
format](https://tools.ietf.org/html/rfc3339#section-5.6). Seconds are
required while fractional seconds are
optional.Note: The regular expression
provides guidance but does not reject all invalid dates.
type: string
minLength: 20
maxLength: 64
pattern: >-
^[0-9]{4}-(0[1-9]|1[0-2])-(0[1-9]|[1-2][0-9]|3[0-1])[T,t]([0-1][0-9]|2[0-3]):[0-5][0-9]:([0-5][0-9]|60)([.][0-9]+)?([Zz]|[+-][0-9]{2}:[0-9]{2})$
card_response:
title: card_response
description: >-
The payment card to use to fund a payment. Card can be a credit or debit
card.
type: object
properties:
name:
description: The card holder's name as it appears on the card.
type: string
minLength: 2
maxLength: 300
pattern: ^[\S\s]*$
last_digits:
description: The last digits of the payment card.
type: string
minLength: 0
maxLength: 2147483647
pattern: ^.*[0-9]{2,}.*$
readOnly: true
brand:
allOf:
- $ref: '#/components/schemas/card_brand'
- description: The card brand or network. Typically used in the response.
readOnly: true
available_networks:
description: Array of brands or networks associated with the card.
type: array
minItems: 1
maxItems: 256
readOnly: true
items:
allOf:
- $ref: '#/components/schemas/card_brand'
- title: card_brand
type:
allOf:
- $ref: '#/components/schemas/card_type'
- description: The payment card type.
authentication_result:
$ref: '#/components/schemas/authentication_response'
attributes:
$ref: '#/components/schemas/card_attributes_response'
from_request:
$ref: '#/components/schemas/card_from_request'
expiry:
allOf:
- $ref: '#/components/schemas/date_year_month'
- description: >-
The card expiration year and month, in [Internet date
format](https://tools.ietf.org/html/rfc3339#section-5.6).
bin_details:
allOf:
- $ref: '#/components/schemas/bin_details'
- description: Bank Identification Number (BIN) details used to fund a payment.
stored_credential:
$ref: '#/components/schemas/card_stored_credential'
paypal_wallet_response:
title: paypal_wallet_response
description: The PayPal Wallet response.
type: object
properties:
email_address:
allOf:
- $ref: '#/components/schemas/email'
- description: The email address of the PayPal account holder.
account_id:
allOf:
- $ref: '#/components/schemas/account_id-2'
- description: The PayPal-assigned ID for the PayPal account holder.
readOnly: true
account_status:
description: >-
The account status indicates whether the buyer has verified the
financial details associated with their PayPal account.
type: string
enum:
- VERIFIED
- UNVERIFIED
readOnly: true
name:
allOf:
- $ref: '#/components/schemas/name'
- description: >-
The name of the PayPal account holder. Supports only the
`given_name` and `surname` properties.
not:
anyOf:
- required:
- prefix
- required:
- middle_name
- required:
- suffix
- required:
- alternate_full_name
- required:
- full_name
phone_type:
$ref: '#/components/schemas/phone_type'
phone_number:
allOf:
- $ref: '#/components/schemas/phone-3'
- description: >-
The phone number, in its canonical international [E.164
numbering plan format](https://www.itu.int/rec/T-REC-E.164/en).
Available only when you enable the **Contact Telephone Number**
option in the **Profile
& Settings** for the merchant's PayPal account. Supports
only the `national_number` property.
birth_date:
allOf:
- $ref: '#/components/schemas/date_no_time'
- description: >-
The birth date of the PayPal account holder in `YYYY-MM-DD`
format.
business_name:
description: >-
The business name of the PayPal account holder (populated for
business accounts only)
type: string
minLength: 0
maxLength: 300
pattern: ^.*$
tax_info:
allOf:
- $ref: '#/components/schemas/tax_info'
- description: >-
The tax information of the PayPal account holder. Required only
for Brazilian PayPal account holder's. Both `tax_id` and
`tax_id_type` are required.
address:
allOf:
- $ref: '#/components/schemas/address_portable'
- description: >-
The address of the PayPal account holder. Supports only the
`address_line_1`, `address_line_2`, `admin_area_1`,
`admin_area_2`, `postal_code`, and `country_code` properties.
Also referred to as the billing address of the customer.
not:
anyOf:
- required:
- address_line_3
- required:
- admin_area_3
- required:
- admin_area_4
- required:
- address_details
attributes:
$ref: '#/components/schemas/paypal_wallet_attributes_response'
stored_credential:
$ref: '#/components/schemas/paypal_wallet_stored_credential'
experience_status:
description: >-
This field indicates the status of PayPal's Checkout experience
throughout the order lifecycle. The values reflect the current stage
of the checkout process.
type: string
enum:
- NOT_STARTED
- IN_PROGRESS
- CANCELED
- APPROVED
readOnly: true
bancontact:
title: bancontact
description: Information used to pay Bancontact.
type: object
properties:
name:
allOf:
- $ref: '#/components/schemas/full_name'
- title: name
description: >-
The name of the account holder associated with this payment
method.
country_code:
allOf:
- $ref: '#/components/schemas/country_code-2'
- description: The two-character ISO 3166-1 country code.
bic:
allOf:
- $ref: '#/components/schemas/bic'
- description: The bank identification code (BIC).
iban_last_chars:
$ref: '#/components/schemas/iban_last_chars'
card_last_digits:
description: The last digits of the card used to fund the Bancontact payment.
type: string
minLength: 4
maxLength: 4
pattern: ^[0-9]{4}$
blik:
title: blik
description: Information used to pay using BLIK.
type: object
properties:
name:
allOf:
- $ref: '#/components/schemas/full_name'
- title: name
description: >-
The name of the account holder associated with this payment
method.
country_code:
allOf:
- $ref: '#/components/schemas/country_code-2'
- description: The two-character ISO 3166-1 country code.
email:
allOf:
- $ref: '#/components/schemas/email_address'
- description: >-
The email address of the account holder associated with this
payment method.
one_click:
allOf:
- $ref: '#/components/schemas/blik_one_click_response'
- description: The one-click integration flow object.
eps:
title: eps
description: Information used to pay using eps.
type: object
properties:
name:
allOf:
- $ref: '#/components/schemas/full_name'
- title: name
description: >-
The name of the account holder associated with this payment
method.
country_code:
allOf:
- $ref: '#/components/schemas/country_code-2'
- description: The two-character ISO 3166-1 country code.
bic:
allOf:
- $ref: '#/components/schemas/bic'
- description: The bank identification code (BIC).
giropay:
title: giropay
description: Information needed to pay using giropay.
type: object
properties:
name:
allOf:
- $ref: '#/components/schemas/full_name'
- title: name
description: >-
The name of the account holder associated with this payment
method.
country_code:
allOf:
- $ref: '#/components/schemas/country_code-2'
- description: The two-character ISO 3166-1 country code.
bic:
allOf:
- $ref: '#/components/schemas/bic'
- description: The bank identification code (BIC).
ideal:
title: ideal
description: Information used to pay using iDEAL.
type: object
properties:
name:
allOf:
- $ref: '#/components/schemas/full_name'
- title: name
description: >-
The name of the account holder associated with this payment
method.
country_code:
allOf:
- $ref: '#/components/schemas/country_code-2'
- description: The two-character ISO 3166-1 country code.
bic:
allOf:
- $ref: '#/components/schemas/bic'
- description: The bank identification code (BIC).
iban_last_chars:
$ref: '#/components/schemas/iban_last_chars'
mybank:
title: mybank
description: Information used to pay using MyBank.
type: object
properties:
name:
allOf:
- $ref: '#/components/schemas/full_name'
- title: name
description: >-
The name of the account holder associated with this payment
method.
country_code:
allOf:
- $ref: '#/components/schemas/country_code-2'
- description: The two-character ISO 3166-1 country code.
bic:
allOf:
- $ref: '#/components/schemas/bic'
- description: The bank identification code (BIC).
iban_last_chars:
$ref: '#/components/schemas/iban_last_chars'
p24:
title: p24
description: Information used to pay using P24(Przelewy24).
type: object
properties:
name:
allOf:
- $ref: '#/components/schemas/full_name'
- title: name
description: >-
The name of the account holder associated with this payment
method.
email:
allOf:
- $ref: '#/components/schemas/email_address'
- description: >-
The email address of the account holder associated with this
payment method.
country_code:
allOf:
- $ref: '#/components/schemas/country_code-2'
- title: name
description: The two-character ISO 3166-1 country code.
payment_descriptor:
description: P24 generated payment description.
type: string
minLength: 1
maxLength: 2000
pattern: ^[\S\s]*$
method_id:
description: >-
Numeric identifier of the payment scheme or bank used for the
payment.
type: string
minLength: 1
maxLength: 300
pattern: ^[\S\s]*$
method_description:
description: Friendly name of the payment scheme or bank used for the payment.
type: string
minLength: 1
maxLength: 2000
pattern: ^[\S\s]*$
sofort:
title: sofort
description: Information used to pay using Sofort.
type: object
properties:
name:
allOf:
- $ref: '#/components/schemas/full_name'
- title: name
description: >-
The name of the account holder associated with this payment
method.
country_code:
allOf:
- $ref: '#/components/schemas/country_code-2'
- description: The two-character ISO 3166-1 country code.
bic:
allOf:
- $ref: '#/components/schemas/bic'
- description: The bank identification code (BIC).
iban_last_chars:
$ref: '#/components/schemas/iban_last_chars'
trustly:
title: trustly
description: Information needed to pay using Trustly.
type: object
properties:
name:
allOf:
- $ref: '#/components/schemas/full_name'
- title: name
description: >-
The name of the account holder associated with this payment
method.
country_code:
allOf:
- $ref: '#/components/schemas/country_code-2'
- description: The two-character ISO 3166-1 country code.
email:
allOf:
- $ref: '#/components/schemas/email_address'
- description: >-
The email address of the account holder associated with this
payment method.
bic:
allOf:
- $ref: '#/components/schemas/bic'
- description: The bank identification code (BIC).
iban_last_chars:
$ref: '#/components/schemas/iban_last_chars'
apple_pay:
title: apple_pay
description: Information needed to pay using ApplePay.
type: object
properties:
id:
description: >-
ApplePay transaction identifier, this will be the unique identifier
for this transaction provided by Apple. The pattern is defined by an
external party and supports Unicode.
type: string
minLength: 1
maxLength: 250
pattern: ^.*$
token:
description: >-
Encrypted ApplePay token, containing card information. This token
would be base64encoded. The pattern is defined by an external party
and supports Unicode.
type: string
minLength: 1
maxLength: 10000
pattern: ^.*$
name:
allOf:
- $ref: '#/components/schemas/full_name'
- description: Name on the wallet.
email_address:
allOf:
- $ref: '#/components/schemas/email_address'
- description: >-
The email address of the account holder associated with this
payment method.
phone_number:
allOf:
- $ref: '#/components/schemas/phone'
- description: >-
The phone number, in its canonical international [E.164
numbering plan format](https://www.itu.int/rec/T-REC-E.164/en).
Supports only the `national_number` property.
not:
anyOf:
- required:
- country_code
- required:
- extension_number
card:
allOf:
- $ref: '#/components/schemas/apple_pay_card_response'
- description: The payment card information.
attributes:
allOf:
- $ref: '#/components/schemas/apple_pay_attributes_response'
- description: Additional attributes associated with apple pay.
stored_credential:
$ref: '#/components/schemas/card_stored_credential'
google_pay:
title: google_pay
description: Google Pay Wallet payment data.
type: object
properties:
name:
allOf:
- $ref: '#/components/schemas/full_name'
- description: Name on the account holder associated with Google Pay.
email_address:
allOf:
- $ref: '#/components/schemas/email_address'
- description: >-
The email address of the account holder associated with Google
Pay.
phone_number:
allOf:
- $ref: >-
#/components/schemas/phone_with_national_required_and_country_code
- description: >-
The phone number of account holder, in its canonical
international [E.164 numbering plan
format](https://www.itu.int/rec/T-REC-E.164/en). Supports only
the `national_number` property.
card:
allOf:
- $ref: '#/components/schemas/google_pay_card_response'
- description: The Card from Google Pay Wallet used to fund the payment.
venmo_wallet_response:
title: venmo_wallet_response
description: Venmo wallet response.
type: object
properties:
email_address:
allOf:
- $ref: '#/components/schemas/email'
- description: The email address of the payer.
account_id:
allOf:
- $ref: '#/components/schemas/account_id-2'
- description: >-
This is an immutable system-generated id for a user's Venmo
account.
readOnly: true
user_name:
description: The Venmo user name chosen by the user, also know as a Venmo handle.
type: string
minLength: 1
maxLength: 50
pattern: ^[-a-zA-Z0-9_]*$
name:
allOf:
- $ref: '#/components/schemas/name'
- description: >-
The name associated with the Venmo account. Supports only the
`given_name` and `surname` properties.
not:
anyOf:
- required:
- prefix
- required:
- middle_name
- required:
- suffix
- required:
- alternate_full_name
- required:
- full_name
phone_number:
allOf:
- $ref: '#/components/schemas/phone-3'
- description: >-
The phone number associated with the Venmo account, in its
canonical international [E.164 numbering plan
format](https://www.itu.int/rec/T-REC-E.164/en). Supports only
the `national_number` property.
address:
allOf:
- $ref: '#/components/schemas/address_portable'
- description: >-
The address of the payer. Supports only the `address_line_1`,
`address_line_2`, `admin_area_1`, `admin_area_2`, `postal_code`,
and `country_code` properties. Also referred to as the billing
address of the customer.
not:
anyOf:
- required:
- address_line_3
- required:
- admin_area_3
- required:
- admin_area_4
- required:
- address_details
return_flow:
description: >-
Merchant preference on how the buyer can navigate back to merchant
website post approving the transaction on the Venmo App.
type: string
enum:
- AUTO
- MANUAL
default: AUTO
readOnly: true
attributes:
$ref: '#/components/schemas/venmo_wallet_attributes_response'
crypto:
title: crypto
description: Pay With Crypto details response object.
type: object
properties:
country_code:
allOf:
- $ref: '#/components/schemas/country_code'
- description: The two-character ISO 3166-1 purchase country code.
name:
allOf:
- $ref: '#/components/schemas/crypto_account_holder_name'
- description: The name of the account holder associated with Crypto wallet.
experience_context:
allOf:
- $ref: '#/components/schemas/experience_context_base'
- description: >-
Customizes the payer experience during the approval process for
the payment.
not:
anyOf:
- required:
- brand_name
- required:
- shipping_preference
payer_base:
title: payer_base
description: >-
The customer who approves and pays for the order. The customer is also
known as the payer.
type: object
properties:
email_address:
allOf:
- $ref: '#/components/schemas/email'
- description: The email address of the payer.
payer_id:
allOf:
- $ref: '#/components/schemas/account_id'
- description: The PayPal-assigned ID for the payer.
readOnly: true
name:
title: Name
description: The name of the party.
type: object
properties:
prefix:
description: The prefix, or title, to the party's name.
type: string
minLength: 0
maxLength: 140
pattern: ^[\S\s]*$
given_name:
description: When the party is a person, the party's given, or first, name.
type: string
minLength: 0
maxLength: 140
pattern: ^[\S\s]*$
surname:
description: >-
When the party is a person, the party's surname or family name. Also
known as the last name. Required when the party is a person. Use
also to store multiple surnames including the matronymic, or
mother's, surname.
type: string
minLength: 0
maxLength: 140
pattern: ^[\S\s]*$
middle_name:
description: >-
When the party is a person, the party's middle name. Use also to
store multiple middle names including the patronymic, or father's,
middle name.
type: string
minLength: 0
maxLength: 140
pattern: ^[\S\s]*$
suffix:
description: The suffix for the party's name.
type: string
minLength: 0
maxLength: 140
pattern: ^[\S\s]*$
full_name:
description: When the party is a person, the party's full name.
type: string
minLength: 0
maxLength: 300
pattern: ^[\S\s]*$
phone_with_type:
title: phone_with_type
description: The phone information.
type: object
required:
- phone_number
properties:
phone_type:
$ref: '#/components/schemas/phone_type'
phone_number:
allOf:
- $ref: '#/components/schemas/phone_number_without_country_code'
- description: >-
The phone number, in its canonical international [E.164
numbering plan format](https://www.itu.int/rec/T-REC-E.164/en).
Supports only the `national_number` property.
date_no_time:
description: >-
The stand-alone date, in [Internet date and time
format](https://tools.ietf.org/html/rfc3339#section-5.6). To represent
special legal values, such as a date of birth, you should use dates with
no associated time or time-zone data. Whenever possible, use the
standard `date_time` type. This regular expression does not validate all
dates. For example, February 31 is valid and nothing is known about leap
years.
type: string
minLength: 10
maxLength: 10
pattern: ^[0-9]{4}-(0[1-9]|1[0-2])-(0[1-9]|[1-2][0-9]|3[0-1])$
tax_info:
title: tax_info
description: >-
The tax ID of the customer. The customer is also known as the payer.
Both `tax_id` and `tax_id_type` are required.
type: object
required:
- tax_id
- tax_id_type
properties:
tax_id:
description: The customer's tax ID value.
type: string
minLength: 1
maxLength: 14
pattern: ^.*([a-zA-Z0-9]).*$
tax_id_type:
description: The customer's tax ID type.
type: string
enum:
- BR_CPF
- BR_CNPJ
address_portable:
title: Portable Postal Address (Medium-Grained)
description: >-
The portable international postal address. Maps to
[AddressValidationMetadata](https://github.com/googlei18n/libaddressinput/wiki/AddressValidationMetadata)
and HTML 5.1 [Autofilling form controls: the autocomplete
attribute](https://www.w3.org/TR/html51/sec-forms.html#autofilling-form-controls-the-autocomplete-attribute).
type: object
required:
- country_code
properties:
address_line_1:
description: >-
The first line of the address, such as number and street, for
example, `173 Drury Lane`. Needed for data entry, and Compliance and
Risk checks. This field needs to pass the full address.
type: string
minLength: 0
maxLength: 300
pattern: ^[\S\s]*$
address_line_2:
description: >-
The second line of the address, for example, a suite or apartment
number.
type: string
minLength: 0
maxLength: 300
pattern: ^[\S\s]*$
address_line_3:
description: >-
The third line of the address, if needed. Examples include a street
complement for Brazil, direction text, such as `next to Walmart`, or
a landmark in an Indian address.
type: string
minLength: 0
maxLength: 100
pattern: ^[\S\s]*$
admin_area_4:
description: >-
The neighborhood, ward, or district. This is smaller than
`admin_area_level_3` or `sub_locality`. Value is:- The postal
sorting code that is used in Guernsey and many French territories,
such as French Guiana.
- The fine-grained administrative
levels in China.
type: string
minLength: 0
maxLength: 100
pattern: ^[\S\s]*$
admin_area_3:
description: >-
The sub-locality, suburb, neighborhood, or district. This is smaller
than `admin_area_level_2`. Value is:- Brazil. Suburb,
*bairro*, or neighborhood.
- India. Sub-locality or district.
Street name information isn't always available, but a sub-locality
or district can be a very small area.
type: string
minLength: 0
maxLength: 100
pattern: ^[\S\s]*$
admin_area_2:
description: A city, town, or village. Smaller than `admin_area_level_1`.
type: string
minLength: 0
maxLength: 120
pattern: ^[\S\s]*$
admin_area_1:
description: >-
The highest-level sub-division in a country, which is usually a
province, state, or ISO-3166-2 subdivision. This data is formatted
for postal delivery, for example, `CA` and not `California`. Value,
by country, is:- UK. A county.
- US. A
state.
- Canada. A province.
- Japan. A
prefecture.
- Switzerland. A *kanton*.
type: string
minLength: 0
maxLength: 300
pattern: ^[\S\s]*$
postal_code:
description: >-
The postal code, which is the ZIP code or equivalent. Typically
required for countries with a postal code or an equivalent. See
[postal code](https://en.wikipedia.org/wiki/Postal_code).
type: string
minLength: 0
maxLength: 60
pattern: ^[\S\s]*$
country_code:
$ref: '#/components/schemas/country_code'
address_details:
title: Address Details
description: >-
The non-portable additional address details include fine-grain
address information for Compliance, Risk, and other scenarios. This
isn't portable with common third-party and open source applications.
This can include data that is redundant with core fields. For
example, `address_portable.address_line_1` is usually a combination
of `address_details.street_number`, `street_name`, and
`street_type`.
type: object
properties:
street_number:
description: The street number.
type: string
minLength: 0
maxLength: 100
pattern: ^[\S\s]*$
street_name:
description: The street name. Just `Drury` in `Drury Lane`.
type: string
minLength: 0
maxLength: 100
pattern: ^[\S\s]*$
street_type:
description: >-
The street type. For example, avenue, boulevard, road, or
expressway.
type: string
minLength: 0
maxLength: 100
pattern: ^[\S\s]*$
delivery_service:
description: >-
The delivery service. Post office box, bag number, or post
office name.
type: string
minLength: 0
maxLength: 100
pattern: ^[\S\s]*$
building_name:
description: >-
A named locations that represents the premise. Usually a
building name or number or collection of buildings with a common
name or number. For example, Craven House.
type: string
minLength: 0
maxLength: 100
pattern: ^[\S\s]*$
sub_building:
description: >-
The first-order entity below a named building or location that
represents the sub-premise. Usually a single building within a
collection of buildings with a common name. Can be a flat,
story, floor, room, or apartment.
type: string
minLength: 0
maxLength: 100
pattern: ^[\S\s]*$
amount_with_breakdown:
title: amount_with_breakdown
description: >-
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.
type: object
allOf:
- $ref: '#/components/schemas/money'
- type: object
properties:
breakdown:
$ref: '#/components/schemas/amount_breakdown'
payee:
title: payee
description: >-
The merchant who receives the funds and fulfills the order. The merchant
is also known as the payee.
type: object
allOf:
- $ref: '#/components/schemas/payee_base'
- type: object
payment_instruction:
title: payment_instruction
description: >-
Any additional payment instructions to be consider during payment
processing. This processing instruction is applicable for Capturing an
order or Authorizing an Order.
type: object
properties:
platform_fees:
description: >-
An array of various fees, commissions, tips, or donations. This
field is only applicable to merchants that been enabled for PayPal
Complete Payments Platform for Marketplaces and Platforms
capability.
type: array
minItems: 0
maxItems: 1
items:
allOf:
- $ref: '#/components/schemas/platform_fee'
- title: platform_fee
disbursement_mode:
allOf:
- $ref: '#/components/schemas/disbursement_mode'
- description: >-
The funds that are held payee by the marketplace/platform. This
field is only applicable to merchants that been enabled for
PayPal Complete Payments Platform for Marketplaces and Platforms
capability.
payee_pricing_tier_id:
description: >-
This field is only enabled for selected merchants/partners to use
and provides the ability to trigger a specific pricing rate/plan for
a payment transaction. The list of eligible 'payee_pricing_tier_id'
would be provided to you by your Account Manager. Specifying values
other than the one provided to you by your account manager would
result in an error.
type: string
minLength: 1
maxLength: 20
pattern: ^.*$
payee_receivable_fx_rate_id:
description: >-
FX identifier generated returned by PayPal to be used for payment
processing in order to honor FX rate (for eligible integrations) to
be used when amount is settled/received into the payee account.
type: string
minLength: 1
maxLength: 4000
pattern: ^.*$
item:
title: item
description: The details for the items to be purchased.
type: object
required:
- name
- quantity
- unit_amount
properties:
name:
description: The item name or title.
type: string
minLength: 1
maxLength: 127
pattern: ^[\S\s]*$
unit_amount:
allOf:
- $ref: '#/components/schemas/money'
- description: >-
The item price or rate per unit. If you specify
unit_amount,
purchase_units[].amount.breakdown.item_total is
required. Must equal unit_amount * quantity for all
items. unit_amount.value can not be a negative
number.
tax:
allOf:
- $ref: '#/components/schemas/money'
- description: >-
The item tax for each unit. If tax is specified,
purchase_units[].amount.breakdown.tax_total is
required. Must equal tax * quantity for all items.
tax.value can not be a negative number.
quantity:
description: The item quantity. Must be a whole number.
type: string
minLength: 0
maxLength: 10
pattern: ^[1-9][0-9]{0,9}$
description:
description: The detailed item description.
type: string
minLength: 0
maxLength: 2048
pattern: ^[\S\s]*$
sku:
description: The stock keeping unit (SKU) for the item.
type: string
minLength: 0
maxLength: 127
pattern: ^[\S\s]*$
url:
description: >-
The URL to the item being purchased. Visible to buyer and used in
buyer experiences.
type: string
minLength: 1
maxLength: 2048
format: uri
category:
description: The item category type.
type: string
enum:
- DIGITAL_GOODS
- PHYSICAL_GOODS
- DONATION
image_url:
description: >-
The URL of the item's image. File type and size restrictions apply.
An image that violates these restrictions will not be honored.
type: string
minLength: 1
maxLength: 2048
format: uri
upc:
allOf:
- $ref: '#/components/schemas/universal_product_code'
- description: The Universal Product Code of the item.
billing_plan:
$ref: '#/components/schemas/order_billing_plan'
shipping_with_tracking_details:
title: shipping_with_tracking_details
description: The order shipping details.
type: object
allOf:
- $ref: '#/components/schemas/shipping_detail'
- type: object
properties:
phone_number:
allOf:
- $ref: >-
#/components/schemas/phone_with_national_required_and_country_code
- description: >-
The phone number of the recipient of the shipped items,
which may belong to either the payer, or an alternate
contact, for delivery.
trackers:
description: An array of trackers for a transaction.
type: array
minItems: 0
maxItems: 32767
items:
$ref: '#/components/schemas/tracker'
supplementary_data:
title: supplementary_data
description: >-
Supplementary data about a payment. This object passes information that
can be used to improve risk assessments and processing costs, for
example, by providing Level 2 and Level 3 payment data.
type: object
properties:
card:
allOf:
- $ref: '#/components/schemas/card_supplementary_data'
- description: >-
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.
risk:
allOf:
- $ref: '#/components/schemas/risk_supplementary_data'
- description: >-
Merchants and partners can add additional customer parameters
that can help with better fraud protection and reduced risk for
unbranded card payments.
payment_collection:
title: Payment Collection
description: >-
The collection of payments, or transactions, for a purchase unit in an
order. For example, authorized payments, captured payments, and refunds.
type: object
properties:
authorizations:
description: >-
An array of authorized payments for a purchase unit. A purchase unit
can have zero or more authorized payments.
type: array
minItems: 0
maxItems: 32767
items:
allOf:
- $ref: '#/components/schemas/authorization_with_additional_data'
- title: authorizations
description: The authorized payment for a purchase unit.
captures:
description: >-
An array of captured payments for a purchase unit. A purchase unit
can have zero or more captured payments.
type: array
minItems: 0
maxItems: 32767
items:
allOf:
- $ref: '#/components/schemas/capture'
- title: capture
description: The captured payment for a purchase unit.
refunds:
description: >-
An array of refunds for a purchase unit. A purchase unit can have
zero or more refunds.
type: array
minItems: 0
maxItems: 32767
items:
allOf:
- $ref: '#/components/schemas/refund'
- title: refund
description: A refund for a purchase unit.
link_schema-2:
title: Link Schema
description: The request data or link target.
type: object
properties:
additionalItems:
title: additional_items
description: Any additional items.
type: object
dependencies:
title: Dependencies
description: Any Dependencies.
type: object
items:
title: Items
description: An item.
type: object
definitions:
title: Definitions
description: Definitions.
type: object
patternProperties:
title: pattern_properties
description: The pattern properties.
type: object
properties:
title: Properties
description: Properties.
type: object
allOf:
title: all_of
description: >-
An array of sub-schemas. The data must validate against all
sub-schemas.
type: array
minItems: 0
maxItems: 32767
items:
title: all_of_item
description: A sub-schema against which the data must validate.
type: object
anyOf:
title: any_of
description: >-
An array of sub-schemas. The data must validate against one or more
sub-schemas.
type: array
minItems: 0
maxItems: 32767
items:
title: any_of_item
description: A sub-schema against which the data must validate.
type: object
oneOf:
title: one_of
description: >-
An array of sub-schemas. The data must validate against one
sub-schema.
type: array
minItems: 0
maxItems: 32767
items:
title: one_of_item
description: A sub-schema against which the data must validate.
type: object
not:
title: Not
description: Not.
type: object
links:
description: An array of links.
type: array
minItems: 0
maxItems: 32767
readOnly: true
items:
title: link
description: A link.
type: object
readOnly: true
fragmentResolution:
title: fragment_resolution
description: The fragment resolution.
type: string
minLength: 0
maxLength: 2147483647
pattern: ^[\S\s]*$
media:
title: Media
description: The media type and context-encoding scheme.
type: object
properties:
type:
description: >-
The media type. See [Multipurpose Internet Mail Extensions
(MIME) Part Two: Media
Types](https://tools.ietf.org/html/rfc2046).
type: string
minLength: 0
maxLength: 2147483647
pattern: ^[\S\s]*$
binaryEncoding:
title: binary_encoding
description: >-
The content-encoding scheme. See [Multipurpose Internet Mail
Extensions (MIME) Part One: Format of Internet Message
Bodies](https://tools.ietf.org/html/rfc2045).
type: string
minLength: 0
maxLength: 2147483647
pattern: ^[\S\s]*$
pathStart:
title: path_start
description: >-
To apply this schema to the instances' URIs, start the URIs with
this value.
type: string
minLength: 0
maxLength: 2147483647
format: uri
link_schema:
title: Link Schema
description: The request data or link target.
type: object
properties:
additionalItems:
title: additional_items
description: Any additional items.
type: object
dependencies:
title: Dependencies
description: The dependencies.
type: object
items:
title: Items
description: An item.
type: object
definitions:
title: Definitions
description: Definitions.
type: object
patternProperties:
title: pattern_properties
description: The pattern properties.
type: object
properties:
title: Properties
description: The properties.
type: object
allOf:
title: all_of
description: >-
An array of sub-schemas. The data must validate against all
sub-schemas.
type: array
minItems: 0
maxItems: 32767
items:
title: all_of_item
description: A sub-schema against which the data must validate.
type: object
anyOf:
title: any_of
description: >-
An array of sub-schemas. The data must validate against one or more
sub-schemas.
type: array
minItems: 0
maxItems: 32767
items:
title: any_of_item
description: A sub-schema against which the data must validate.
type: object
oneOf:
title: one_of
description: >-
An array of sub-schemas. The data must validate against one
sub-schema.
type: array
minItems: 0
maxItems: 32767
items:
title: one_of_item
description: A sub-schema against which the data must validate.
type: object
not:
title: Not
description: Not.
type: object
links:
description: An array of links.
type: array
minItems: 0
maxItems: 32767
readOnly: true
items:
title: link
description: A link.
type: object
readOnly: true
fragmentResolution:
title: fragment_resolution
description: The fragment resolution.
type: string
minLength: 0
maxLength: 2147483647
pattern: ^[\S\s]*$
media:
title: Media
description: The media type and context-encoding scheme.
type: object
properties:
type:
description: >-
The media type. See [Multipurpose Internet Mail Extensions
(MIME) Part Two: Media
Types](https://tools.ietf.org/html/rfc2046).
type: string
minLength: 0
maxLength: 2147483647
pattern: ^[\S\s]*$
binaryEncoding:
title: binary_encoding
description: >-
The content-encoding scheme. See [Multipurpose Internet Mail
Extensions (MIME) Part One: Format of Internet Message
Bodies](https://tools.ietf.org/html/rfc2045).
type: string
minLength: 0
maxLength: 2147483647
pattern: ^[\S\s]*$
pathStart:
title: path_start
description: >-
To apply this schema to the instances' URIs, start the URIs with
this value.
type: string
minLength: 0
maxLength: 2147483647
format: uri
card:
title: card
description: >-
The payment card to use to fund a payment. Can be a credit or debit
card.
type: object
properties:
id:
allOf:
- $ref: '#/components/schemas/instrument_id'
- description: The PayPal-generated ID for the card.
readOnly: true
name:
description: The card holder's name as it appears on the card.
type: string
minLength: 1
maxLength: 300
pattern: ^.{1,300}$
number:
description: The primary account number (PAN) for the payment card.
type: string
minLength: 13
maxLength: 19
pattern: ^[0-9]{13,19}$
expiry:
allOf:
- $ref: '#/components/schemas/date_year_month'
- description: >-
The card expiration year and month, in [Internet date
format](https://tools.ietf.org/html/rfc3339#section-5.6) For
example: 2028-04
security_code:
description: >-
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`.
type: string
minLength: 3
maxLength: 4
pattern: ^[0-9]{3,4}$
last_digits:
description: The last digits of the payment card.
type: string
minLength: 2
maxLength: 4
pattern: ^[0-9]{2,4}$
readOnly: true
card_type:
allOf:
- $ref: '#/components/schemas/card_brand'
- description: >-
The card brand or network. Typically used in the response.
DEPRECATED
deprecated: true
readOnly: true
type:
allOf:
- $ref: '#/components/schemas/card_type'
- description: The payment card type.
brand:
allOf:
- $ref: '#/components/schemas/card_brand'
- description: The card brand or network. Typically used in the response.
billing_address:
allOf:
- $ref: '#/components/schemas/address_portable'
- description: >-
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.
not:
anyOf:
- required:
- address_line_3
- required:
- admin_area_3
- required:
- admin_area_4
- required:
- address_details
attributes:
allOf:
- $ref: '#/components/schemas/card_attributes'
- title: card_attributes
description: Additional attributes associated with the use of this card.
vault_id:
title: vault_id
description: >-
The PayPal-generated ID for the vaulted payment source. This ID should
be stored on the merchant's server so the saved payment source can be
used for future transactions.
type: string
minLength: 1
maxLength: 255
pattern: ^[0-9a-zA-Z_-]+$
single_use_token:
title: single_use_token
description: >-
The PayPal-generated, short-lived, one-time-use token, used to
communicate payment information to PayPal for transaction processing.
type: string
minLength: 1
maxLength: 255
pattern: ^[0-9a-zA-Z_-]+$
card_stored_credential:
title: card_stored_credential
description: >-
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.
type: object
required:
- payment_initiator
- payment_type
properties:
payment_initiator:
$ref: '#/components/schemas/payment_initiator'
payment_type:
$ref: '#/components/schemas/stored_payment_source_payment_type'
usage:
$ref: '#/components/schemas/stored_payment_source_usage_type'
previous_network_transaction_reference:
$ref: '#/components/schemas/network_transaction_reference'
network_token_request:
title: network_token
description: The Third Party Network token used to fund a payment.
type: object
required:
- expiry
- number
properties:
number:
description: Third party network token number.
type: string
minLength: 13
maxLength: 19
pattern: ^[0-9]{13,19}$
expiry:
allOf:
- $ref: '#/components/schemas/date_year_month'
- description: >-
The card expiration year and month, in [Internet date
format](https://tools.ietf.org/html/rfc3339#section-5.6).
cryptogram:
description: >-
An Encrypted one-time use value that's sent along with Network
Token. This field is not required to be present for recurring
transactions.
type: string
minLength: 28
maxLength: 32
pattern: ^.*$
eci_flag:
$ref: '#/components/schemas/eci_flag'
token_requestor_id:
description: >-
A TRID, or a Token Requestor ID, is an identifier used by merchants
to request network tokens from card networks. A TRID is a precursor
to obtaining a network token for a credit card primary account
number (PAN), and will aid in enabling secure card on file (COF)
payments and reducing fraud.
type: string
minLength: 1
maxLength: 11
pattern: ^[0-9A-Z_]+$
card_experience_context:
title: card_experience_context
description: Customizes the payer experience during the 3DS Approval for payment.
type: object
properties:
return_url:
allOf:
- $ref: '#/components/schemas/url'
- description: >-
The URL where the customer will be redirected upon successfully
completing the 3DS challenge.
type: string
minLength: 10
maxLength: 4000
format: uri
cancel_url:
allOf:
- $ref: '#/components/schemas/url'
- description: >-
The URL where the customer will be redirected upon cancelling
the 3DS challenge.
type: string
minLength: 10
maxLength: 4000
format: uri
email:
title: email
description: >-
The internationalized email address.Note:
Up to 64 characters are allowed before and 255 characters are allowed
after the @ sign. However, the generally accepted maximum
length for an email address is 254 characters. The pattern verifies that
an unquoted @ sign exists.
type: string
minLength: 3
maxLength: 254
pattern: >-
^.*(?:[a-zA-Z0-9!#$%&'*+/=?^_`{|}~-]+(?:\.[a-zA-Z0-9!#$%&'*+/=?^_`{|}~-]+)*|(?:[\x01-\x08\x0b\x0c\x0e-\x1f\x21\x23-\x5b\x5d-\x7f]|\[\x01-\x09\x0b\x0c\x0e-\x7f])*")@(?:(?:[a-zA-Z0-9](?:[a-zA-Z0-9-]*[a-zA-Z0-9])?\.)+[a-zA-Z0-9](?:[a-zA-Z0-9-]*[a-zA-Z0-9])?|\[(?:(?:(2(5[0-5]|[0-4][0-9])|1[0-9][0-9]|[1-9]?[0-9]))\.){3}(?:(2(5[0-5]|[0-4][0-9])|1[0-9][0-9]|[1-9]?[0-9])|[a-zA-Z0-9-]*[a-zA-Z0-9]:(?:[\x01-\x08\x0b\x0c\x0e-\x1f\x21-\x5a\x53-\x7f]|\[\x01-\x09\x0b\x0c\x0e-\x7f])+)\]).*$
paypal_wallet_attributes:
title: paypal_wallet_attributes
description: Additional attributes associated with the use of this PayPal Wallet.
type: object
properties:
customer:
$ref: '#/components/schemas/paypal_wallet_customer'
vault:
allOf:
- $ref: '#/components/schemas/vault_paypal_wallet_base'
- description: >-
Attributes used to provide the instructions during vaulting of
the PayPal Wallet.
not:
required:
- shipping
paypal_wallet_experience_context:
title: paypal_wallet_experience_context
description: >-
Customizes the payer experience during the approval process for payment
with PayPal.Note: Partners and Marketplaces
might configure brand_name and
shipping_preference during partner account setup, which
overrides the request values.
type: object
properties:
brand_name:
description: >-
The label that overrides the business name in the PayPal account on
the PayPal site. The pattern is defined by an external party and
supports Unicode.
type: string
minLength: 1
maxLength: 127
pattern: ^.*$
locale:
allOf:
- $ref: '#/components/schemas/language'
- description: >-
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`.
shipping_preference:
description: The location from which the shipping address is derived.
type: string
enum:
- GET_FROM_FILE
- NO_SHIPPING
- SET_PROVIDED_ADDRESS
default: GET_FROM_FILE
contact_preference:
description: >-
The preference to display the contact information (buyer’s shipping
email & phone number) on PayPal's checkout for easy merchant-buyer
communication.
type: string
enum:
- NO_CONTACT_INFO
- UPDATE_CONTACT_INFO
- RETAIN_CONTACT_INFO
default: NO_CONTACT_INFO
return_url:
allOf:
- $ref: '#/components/schemas/url'
- description: >-
The URL where the customer will be redirected upon approving a
payment.
format: uri
cancel_url:
allOf:
- $ref: '#/components/schemas/url'
- description: >-
The URL where the customer will be redirected upon cancelling
the payment approval.
format: uri
app_switch_context:
allOf:
- $ref: '#/components/schemas/app_switch_context'
- description: >-
Merchants can use this to switch buyers from their
website/application to the PayPal consumer app to review and
approve the transaction.
landing_page:
description: >-
The type of landing page to show on the PayPal site for customer
checkout.
type: string
enum:
- LOGIN
- GUEST_CHECKOUT
- NO_PREFERENCE
- BILLING
default: NO_PREFERENCE
user_action:
description: >-
Configures a Continue or Pay Now
checkout flow.
type: string
enum:
- CONTINUE
- PAY_NOW
default: CONTINUE
payment_method_preference:
description: The merchant-preferred payment methods.
type: string
enum:
- UNRESTRICTED
- IMMEDIATE_PAYMENT_REQUIRED
default: UNRESTRICTED
order_update_callback_config:
allOf:
- $ref: '#/components/schemas/callback_configuration'
- description: >-
Merchant provided Order Update callback configuration for PayPal
Wallet.PayPal will call back merchant when the specified event
occurs.we recommend merchants to pass both the shipping_options
and shipping_address callback events. Not supported when
`shipping.type` is specified or when
'application_context.shipping_preference' is set as
'NO_SHIPPING' or 'SET_PROVIDED_ADDRESS'.
billing_agreement_id:
title: billing_agreement_id
description: >-
The PayPal billing agreement ID. References an approved recurring
payment for goods or services.
type: string
minLength: 2
maxLength: 128
pattern: ^[a-zA-Z0-9-]+$
paypal_wallet_stored_credential:
title: paypal_wallet_stored_credential
description: >-
Provides additional details to process a payment using the PayPal wallet
billing agreement or a vaulted payment method that has been stored or is
intended to be stored.
type: object
required:
- payment_initiator
properties:
payment_initiator:
$ref: '#/components/schemas/payment_initiator'
charge_pattern:
allOf:
- $ref: '#/components/schemas/charge_pattern'
- description: >-
DEPRECATED. Expected business/pricing model for the billing
agreement, Please use usage_pattern instead.
DEPRECATED
deprecated: true
usage_pattern:
$ref: '#/components/schemas/charge_pattern'
usage:
$ref: '#/components/schemas/stored_payment_source_usage_type'
full_name:
title: name
description: The full name representation like Mr J Smith.
type: string
minLength: 3
maxLength: 300
pattern: ^[\S\s]*$
country_code-2:
description: >-
The [two-character ISO 3166-1 code](/api/rest/reference/country-codes/)
that identifies the country or region.Note:
The country code for Great Britain is GB and not
UK as used in the top-level domain names for that country.
Use the `C2` country code for China worldwide for comparable
uncontrolled price (CUP) method, bank card, and cross-border
transactions.
type: string
minLength: 2
maxLength: 2
pattern: ^([A-Z]{2}|C2)$
experience_context_base:
title: experience_context_base
description: >-
Customizes the payer experience during the approval process for the
payment.
type: object
properties:
brand_name:
description: >-
The label that overrides the business name in the PayPal account on
the PayPal site. The pattern is defined by an external party and
supports Unicode.
type: string
minLength: 1
maxLength: 127
pattern: ^.*$
locale:
allOf:
- $ref: '#/components/schemas/language'
- description: >-
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`.
shipping_preference:
description: The location from which the shipping address is derived.
type: string
enum:
- GET_FROM_FILE
- NO_SHIPPING
- SET_PROVIDED_ADDRESS
default: GET_FROM_FILE
return_url:
allOf:
- $ref: '#/components/schemas/url'
- description: >-
The URL where the customer is redirected after the customer
approves the payment.
format: uri
cancel_url:
allOf:
- $ref: '#/components/schemas/url'
- description: >-
The URL where the customer is redirected after the customer
cancels the payment.
format: uri
email_address:
description: >-
The internationalized email address.Note:
Up to 64 characters are allowed before and 255 characters are allowed
after the @ sign. However, the generally accepted maximum
length for an email address is 254 characters. The pattern verifies that
an unquoted @ sign exists.
type: string
minLength: 3
maxLength: 254
pattern: >-
^(?:[A-Za-z0-9!#$%&'*+/=?^_`{|}~-]+(?:\.[A-Za-z0-9!#$%&'*+/=?^_`{|}~-]+)*|"(?:[\x01-\x08\x0b\x0c\x0e-\x1f\x21\x23-\x5b\x5d-\x7f]|\\[\x01-\x09\x0b\x0c\x0e-\x7f])*")@(?:(?:[A-Za-z0-9](?:[A-Za-z0-9-]*[A-Za-z0-9])?\.)+[A-Za-z0-9](?:[A-Za-z0-9-]*[A-Za-z0-9])?|\[(?:(?:25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?)\.){3}(?:25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?|[A-Za-z0-9-]*[A-Za-z0-9]:(?:[\x01-\x08\x0b\x0c\x0e-\x1f\x21-\x5a\x53-\x7f]|\\[\x01-\x09\x0b\x0c\x0e-\x7f])+)\])$
blik_experience_context:
title: blik_experience_context
description: >-
Customizes the payer experience during the approval process for the BLIK
payment.
type: object
allOf:
- $ref: '#/components/schemas/experience_context_base'
- type: object
properties:
consumer_ip:
allOf:
- $ref: '#/components/schemas/ip_address'
- description: >-
The IP address of the consumer. It could be either IPv4 or
IPv6.
consumer_user_agent:
description: >-
The payer's User Agent. For example, Mozilla/5.0 (Macintosh;
Intel Mac OS X x.y; rv:42.0).
type: string
minLength: 1
maxLength: 256
pattern: ^.*$
blik_seamless:
title: blik_level_0
description: Information used to pay using BLIK level_0 flow.
type: object
required:
- auth_code
properties:
auth_code:
description: The 6-digit code used to authenticate a consumer within BLIK.
type: string
minLength: 6
maxLength: 6
pattern: ^[0-9]{6}$
blik_one_click:
title: blik_one_click
description: Information used to pay using BLIK one-click flow.
type: object
required:
- consumer_reference
properties:
auth_code:
description: The 6-digit code used to authenticate a consumer within BLIK.
type: string
minLength: 6
maxLength: 6
pattern: ^[0-9]{6}$
consumer_reference:
description: >-
The merchant generated, unique reference serving as a primary
identifier for accounts connected between Blik and a merchant.
type: string
minLength: 3
maxLength: 64
pattern: ^[ -~]{3,64}$
alias_label:
description: >-
A bank defined identifier used as a display name to allow the payer
to differentiate between multiple registered bank accounts.
type: string
minLength: 8
maxLength: 35
pattern: ^[ -~]{8,35}$
alias_key:
description: >-
A Blik-defined identifier for a specific Blik-enabled bank account
that is associated with a given merchant. Used only in conjunction
with a Consumer Reference.
type: string
minLength: 1
maxLength: 19
pattern: ^[0-9]+$
bic:
title: BIC
description: >-
The business identification code (BIC). In payments systems, a BIC is
used to identify a specific business, most commonly a bank.
type: string
minLength: 8
maxLength: 11
pattern: ^[A-Z-a-z0-9]{4}[A-Z-a-z]{2}[A-Z-a-z0-9]{2}([A-Z-a-z0-9]{3})?$
phone_number_without_country_code:
title: Phone Number Format Requiring National Number Excluding Country Code
description: >-
A structured representation of a phone number conforming to the
international [E.164 numbering plan
format](https://www.itu.int/rec/T-REC-E.164/en),requiring only the
national_number field.
type: object
required:
- national_number
properties:
national_number:
description: >-
The national number, in its canonical international [E.164 numbering
plan format](https://www.itu.int/rec/T-REC-E.164/en). The combined
length of the country calling code (CC) and the national number must
not be greater than 15 digits. The national number consists of a
national destination code (NDC) and subscriber number (SN).
type: string
minLength: 1
maxLength: 14
pattern: ^[0-9]{1,14}?$
apple_pay_decrypted_token_data:
title: apple_pay_decrypted_token_data
description: >-
Information about the Payment data obtained by decrypting Apple Pay
token.
type: object
required:
- tokenized_card
properties:
transaction_amount:
allOf:
- $ref: '#/components/schemas/money'
- description: >-
The transaction amount for the payment that the payer has
approved on apple platform.
tokenized_card:
allOf:
- $ref: '#/components/schemas/card'
- description: Apple Pay tokenized credit card used to pay.
not:
anyOf:
- required:
- id
- required:
- security_code
- required:
- last_digits
- required:
- authentication_results
- required:
- attributes
device_manufacturer_id:
description: >-
Apple Pay Hex-encoded device manufacturer identifier. The pattern is
defined by an external party and supports Unicode.
type: string
minLength: 1
maxLength: 2000
pattern: ^.*$
payment_data_type:
description: >-
Indicates the type of payment data passed, in case of Non China the
payment data is 3DSECURE and for China it is EMV.
type: string
enum:
- 3DSECURE
- EMV
payment_data:
allOf:
- $ref: '#/components/schemas/apple_pay_payment_data'
- description: >-
Apple Pay payment data object which contains the cryptogram,
eci_indicator and other data.
apple_pay_attributes:
title: apple_pay_attributes
description: Additional attributes associated with apple pay.
type: object
properties:
customer:
$ref: '#/components/schemas/customer'
vault:
$ref: '#/components/schemas/v3_vault_instruction_base'
apple_pay_experience_context:
title: apple_pay_experience_context
description: >-
Customizes the payer experience during the approval process for the
payment.
type: object
required:
- cancel_url
- return_url
properties:
return_url:
allOf:
- $ref: '#/components/schemas/url'
- description: >-
The URL where the customer is redirected after the customer
approves the payment.
format: uri
cancel_url:
allOf:
- $ref: '#/components/schemas/url'
- description: >-
The URL where the customer is redirected after the customer
cancels the payment.
format: uri
phone_with_national_required_and_country_code:
title: >-
Phone Number Schema with Required National Number and Optional Country
Code
description: >-
A structured representation of a phone number conforming to the
international [E.164 numbering plan
format](https://www.itu.int/rec/T-REC-E.164/en),requiring the
national_number field and optionally supporting the country_code.
type: object
required:
- national_number
properties:
country_code:
title: country_calling_code
description: >-
The country calling code (CC), in its canonical international [E.164
numbering plan format](https://www.itu.int/rec/T-REC-E.164/en). The
combined length of the CC and the national number must not be
greater than 15 digits. The national number consists of a national
destination code (NDC) and subscriber number (SN).
type: string
minLength: 1
maxLength: 3
pattern: ^[0-9]{1,3}?$
national_number:
description: >-
The national number, in its canonical international [E.164 numbering
plan format](https://www.itu.int/rec/T-REC-E.164/en). The combined
length of the country calling code (CC) and the national number must
not be greater than 15 digits. The national number consists of a
national destination code (NDC) and subscriber number (SN).
type: string
minLength: 1
maxLength: 14
pattern: ^[0-9]{1,14}?$
google_pay_card:
title: google_pay_card
description: >-
The payment card used to fund a Google Pay payment. Can be a credit or
debit card.
type: object
properties:
name:
description: The card holder's name as it appears on the card.
type: string
minLength: 1
maxLength: 300
pattern: ^.{1,300}$
number:
description: The primary account number (PAN) for the payment card.
type: string
minLength: 13
maxLength: 19
pattern: ^[0-9]{13,19}$
expiry:
allOf:
- $ref: '#/components/schemas/date_year_month'
- description: >-
The card expiration year and month, in [Internet date
format](https://tools.ietf.org/html/rfc3339#section-5.6).
last_digits:
description: The last digits of the payment card.
type: string
minLength: 2
maxLength: 4
pattern: ^[0-9]{2,4}$
readOnly: true
type:
allOf:
- $ref: '#/components/schemas/card_type'
- description: The payment card type.
brand:
allOf:
- $ref: '#/components/schemas/card_brand'
- description: The card brand or network. Typically used in the response.
billing_address:
allOf:
- $ref: '#/components/schemas/address_portable'
- description: >-
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.
not:
anyOf:
- required:
- address_line_3
- required:
- admin_area_3
- required:
- admin_area_4
- required:
- address_details
google_pay_decrypted_token_data:
title: google_pay_decrypted_token_data
description: >-
Details shared by Google for the merchant to be shared with PayPal. This
is required to process the transaction using the Google Pay payment
method.
type: object
required:
- authentication_method
- card
- payment_method
properties:
message_id:
description: >-
A unique ID that identifies the message in case it needs to be
revoked or located at a later time.
type: string
minLength: 1
maxLength: 250
pattern: ^.*$
message_expiration:
description: >-
Date and time at which the message expires as UTC milliseconds since
epoch. Integrators should reject any message that's expired.
type: string
minLength: 13
maxLength: 13
pattern: ^\d{13}$
payment_method:
description: >-
The type of the payment credential. Currently, only CARD is
supported.
type: string
enum:
- CARD
card:
description: Google Pay tokenized credit card used to pay.
allOf:
- $ref: '#/components/schemas/google_pay_card'
- required:
- number
- expiry
authentication_method:
description: Authentication Method which is used for the card transaction.
type: string
enum:
- PAN_ONLY
- CRYPTOGRAM_3DS
cryptogram:
description: >-
Base-64 cryptographic identifier used by card schemes to validate
the token verification result. This is a conditionally required
field if authentication_method is CRYPTOGRAM_3DS.
type: string
minLength: 1
maxLength: 2000
pattern: ^[\S\s]*$
eci_indicator:
description: >-
Electronic Commerce Indicator may not always be present. It is only
returned for tokens on the Visa card network. This value is passed
through in the payment authorization request.
type: string
minLength: 1
maxLength: 256
pattern: ^.*$
assurance_details:
title: assurance_details
description: >-
Information about cardholder possession validation and cardholder
identification and verifications (ID&V).
type: object
properties:
account_verified:
description: >-
If true, indicates that Cardholder possession validation has been
performed on returned payment credential.
type: boolean
default: false
card_holder_authenticated:
description: >-
If true, indicates that identification and verifications (ID&V) was
performed on the returned payment credential.If false, the same
risk-based authentication can be performed as you would for card
transactions. This risk-based authentication can include, but not
limited to, step-up with 3D Secure protocol if applicable.
type: boolean
default: false
google_pay_experience_context:
title: google_pay_experience_context
description: >-
Customizes the payer experience during the approval process for the
payment.
type: object
required:
- cancel_url
- return_url
properties:
return_url:
allOf:
- $ref: '#/components/schemas/url'
- description: >-
The URL where the customer is redirected after the customer
approves the payment.
format: uri
cancel_url:
allOf:
- $ref: '#/components/schemas/url'
- description: >-
The URL where the customer is redirected after the customer
cancels the payment.
format: uri
venmo_wallet_experience_context:
title: venmo_wallet_experience_context
description: >-
Customizes the buyer experience during the approval process for payment
with Venmo.Note: Partners and Marketplaces
might configure shipping_preference during partner account
setup, which overrides the request values.
type: object
properties:
brand_name:
description: >-
The business name of the merchant. The pattern is defined by an
external party and supports Unicode.
type: string
minLength: 1
maxLength: 127
pattern: ^.*$
shipping_preference:
description: The location from which the shipping address is derived.
type: string
enum:
- GET_FROM_FILE
- NO_SHIPPING
- SET_PROVIDED_ADDRESS
default: GET_FROM_FILE
order_update_callback_config:
allOf:
- $ref: '#/components/schemas/callback_configuration'
- description: >-
Merchant provided Order Update callback configuration for Venmo
Wallet.Venmo will call back merchant when the specified event
occurs.we recommend merchants to pass both the shipping_options
and shipping_address callback events. Not supported when
`shipping.type` is specified or when
'application_context.shipping_preference' is set as
'NO_SHIPPING' or 'SET_PROVIDED_ADDRESS'.
user_action:
description: >-
Configures a Continue or Pay Now
checkout flow.
type: string
enum:
- CONTINUE
- PAY_NOW
default: CONTINUE
venmo_wallet_attributes:
title: venmo_wallet_attributes
description: Additional attributes associated with the use of this Venmo Wallet.
type: object
properties:
customer:
$ref: '#/components/schemas/venmo_wallet_customer'
vault:
allOf:
- $ref: '#/components/schemas/vault_venmo_wallet_base'
- description: >-
Attributes used to provide the instructions during vaulting of
the Venmo Wallet.
country_code:
description: >-
The [2-character ISO 3166-1 code](/api/rest/reference/country-codes/)
that identifies the country or region.Note:
The country code for Great Britain is GB and not
UK as used in the top-level domain names for that country.
Use the `C2` country code for China worldwide for comparable
uncontrolled price (CUP) method, bank card, and cross-border
transactions.
type: string
minLength: 2
maxLength: 2
pattern: ^([A-Z]{2}|C2)$
crypto_account_holder_name:
title: crypto_account_holder_name
description: Crypto account holder name.
type: object
required:
- given_name
- surname
properties:
prefix:
description: The prefix, or title, to the account holder's name.
type: string
minLength: 1
maxLength: 140
pattern: ^[\S\s]*$
given_name:
description: >-
When the account holder is a person, the account holder's given, or
first, name.
type: string
minLength: 1
maxLength: 140
pattern: ^[\S\s]*$
surname:
description: >-
When the account holder is a person, the account holder's surname or
family name. Also known as the last name. Required when the account
holder is a person. Use also to store multiple surnames including
the matronymic, or mother's, surname.
type: string
minLength: 1
maxLength: 140
pattern: ^[\S\s]*$
middle_name:
description: >-
When the account holder is a person, the account holder's middle
name. Use also to store multiple middle names including the
patronymic, or father's, middle name.
type: string
minLength: 1
maxLength: 140
pattern: ^[\S\s]*$
experience_context_base_without_brand_shipping:
title: experience_context_base
description: >-
Customizes the payer experience during the approval process for the
payment.
type: object
required:
- cancel_url
- return_url
properties:
locale:
allOf:
- $ref: '#/components/schemas/language'
- description: >-
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`.
return_url:
allOf:
- $ref: '#/components/schemas/url'
- description: >-
The URL where the customer is redirected after the customer
approves the payment.
format: uri
cancel_url:
allOf:
- $ref: '#/components/schemas/url'
- description: >-
The URL where the customer is redirected after the customer
cancels the payment.
format: uri
card_brand:
title: card_brand
description: >-
The card network or brand. Applies to credit, debit, gift, and payment
cards.
type: string
enum:
- VISA
- MASTERCARD
- DISCOVER
- AMEX
- SOLO
- JCB
- STAR
- DELTA
- SWITCH
- MAESTRO
- CB_NATIONALE
- CONFIGOGA
- CONFIDIS
- ELECTRON
- CETELEM
- CHINA_UNION_PAY
- DINERS
- ELO
- HIPER
- HIPERCARD
- RUPAY
- GE
- SYNCHRONY
- EFTPOS
- CARTE_BANCAIRE
- STAR_ACCESS
- PULSE
- NYCE
- ACCEL
- UNKNOWN
card_type:
title: card_type
description: Type of card. i.e Credit, Debit and so on.
type: string
enum:
- CREDIT
- DEBIT
- PREPAID
- STORE
- UNKNOWN
authentication_response:
title: authentication_response
description: Results of Authentication such as 3D Secure.
type: object
properties:
liability_shift:
$ref: '#/components/schemas/liability_shift'
three_d_secure:
$ref: '#/components/schemas/three_d_secure_authentication_response'
card_attributes_response:
title: card_attributes_response
description: Additional attributes associated with the use of this card.
type: object
properties:
vault:
$ref: '#/components/schemas/card_vault_response'
card_from_request:
title: card_from_request
description: Representation of card details as received in the request.
type: object
properties:
expiry:
allOf:
- $ref: '#/components/schemas/date_year_month'
- description: >-
The card expiration year and month, in [Internet date
format](https://tools.ietf.org/html/rfc3339#section-5.6).
last_digits:
description: The last digits of the payment card.
type: string
minLength: 2
maxLength: 4
pattern: ^.*[0-9]{2,}.*$
readOnly: true
date_year_month:
description: >-
The year and month, in ISO-8601 `YYYY-MM` date format. See [Internet
date and time format](https://tools.ietf.org/html/rfc3339#section-5.6).
type: string
minLength: 7
maxLength: 7
pattern: ^[0-9]{4}-(0[1-9]|1[0-2])$
bin_details:
title: bin_details
description: Bank Identification Number (BIN) details used to fund a payment.
type: object
properties:
bin:
description: >-
The Bank Identification Number (BIN) signifies the number that is
being used to identify the granular level details (except the PII
information) of the card.
type: string
minLength: 1
maxLength: 25
pattern: ^[0-9]+$
issuing_bank:
description: The issuer of the card instrument.
type: string
minLength: 1
maxLength: 64
pattern: ^[\S\s]*$
bin_country_code:
allOf:
- $ref: '#/components/schemas/country_code-2'
- description: >-
The [two-character ISO-3166-1 country
code](/docs/integration/direct/rest/country-codes/) of the bank.
products:
description: >-
The type of card product assigned to the BIN by the issuer. These
values are defined by the issuer and may change over time. Some
examples include: PREPAID_GIFT, CONSUMER, CORPORATE.
type: array
minItems: 1
maxItems: 256
items:
title: products
description: This value provides the category of the BIN.
type: string
minLength: 1
maxLength: 255
pattern: ^[\S\s]*$
account_id-2:
description: >-
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.
type: string
minLength: 13
maxLength: 13
pattern: ^[2-9A-HJ-NP-Z]{13}$
phone_type:
title: Phone Type
description: The phone type.
type: string
enum:
- FAX
- HOME
- MOBILE
- OTHER
- PAGER
phone-3:
title: Phone Number
description: >-
The phone number in its canonical international [E.164 numbering plan
format](https://www.itu.int/rec/T-REC-E.164/en).
type: object
required:
- national_number
properties:
national_number:
description: >-
The national number, in its canonical international [E.164 numbering
plan format](https://www.itu.int/rec/T-REC-E.164/en). The combined
length of the country calling code (CC) and the national number must
not be greater than 15 digits. The national number consists of a
national destination code (NDC) and subscriber number (SN).
type: string
minLength: 1
maxLength: 14
pattern: ^[0-9]{1,14}?$
paypal_wallet_attributes_response:
title: paypal_wallet_attributes_response
description: Additional attributes associated with the use of a PayPal Wallet.
type: object
properties:
vault:
$ref: '#/components/schemas/paypal_wallet_vault_response'
cobranded_cards:
description: >-
An array of merchant cobranded cards used by buyer to complete an
order. This array will be present if a merchant has onboarded their
cobranded card with PayPal and provided corresponding label(s).
type: array
minItems: 0
maxItems: 25
items:
allOf:
- $ref: '#/components/schemas/cobranded_card'
- title: cobranded_card
iban_last_chars:
title: iban_last_chars
description: The last characters of the IBAN used to pay.
type: string
minLength: 4
maxLength: 34
pattern: ^.*[a-zA-Z0-9]{4}.*$
blik_one_click_response:
title: blik_one_click_response
description: Information used to pay using BLIK one-click flow.
type: object
properties:
consumer_reference:
description: >-
The merchant generated, unique reference serving as a primary
identifier for accounts connected between Blik and a merchant.
type: string
minLength: 3
maxLength: 64
pattern: ^[ -~]{3,64}$
phone:
title: Phone
description: >-
The phone number, in its canonical international [E.164 numbering plan
format](https://www.itu.int/rec/T-REC-E.164/en).
type: object
required:
- country_code
- national_number
properties:
country_code:
title: country_calling_code
description: >-
The country calling code (CC), in its canonical international [E.164
numbering plan format](https://www.itu.int/rec/T-REC-E.164/en). The
combined length of the CC and the national number must not be
greater than 15 digits. The national number consists of a national
destination code (NDC) and subscriber number (SN).
type: string
minLength: 1
maxLength: 3
pattern: ^[0-9]{1,3}?$
national_number:
description: >-
The national number, in its canonical international [E.164 numbering
plan format](https://www.itu.int/rec/T-REC-E.164/en). The combined
length of the country calling code (CC) and the national number must
not be greater than 15 digits. The national number consists of a
national destination code (NDC) and subscriber number (SN).
type: string
minLength: 1
maxLength: 14
pattern: ^[0-9]{1,14}?$
extension_number:
description: The extension number.
type: string
minLength: 1
maxLength: 15
pattern: ^[0-9]{1,15}?$
apple_pay_card_response:
title: apple_pay_card_response
description: The Card from Apple Pay Wallet used to fund the payment.
type: object
allOf:
- allOf:
- $ref: '#/components/schemas/card_response'
- not:
anyOf:
- required:
- id
- required:
- last_n_chars
- required:
- issuer
- type: object
properties:
name:
description: The card holder's name as it appears on the card.
type: string
minLength: 0
maxLength: 300
pattern: ^[\S\s]*$
billing_address:
allOf:
- $ref: '#/components/schemas/address_portable'
- description: >-
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.
not:
anyOf:
- required:
- address_line_3
- required:
- admin_area_3
- required:
- admin_area_4
- required:
- address_details
country_code:
allOf:
- $ref: '#/components/schemas/country_code-2'
- description: The country where the card is issued.
apple_pay_attributes_response:
title: apple_pay_attributes_response
description: Additional attributes associated with the use of Apple Pay.
type: object
properties:
vault:
$ref: '#/components/schemas/vault_response'
google_pay_card_response:
title: google_pay_card_response
description: >-
The payment card to use to fund a Google Pay payment response. Can be a
credit or debit card.
type: object
properties:
name:
description: The card holder's name as it appears on the card.
type: string
minLength: 1
maxLength: 300
pattern: ^.{1,300}$
last_digits:
description: The last digits of the payment card.
type: string
minLength: 2
maxLength: 4
pattern: ^[0-9]{2,4}$
readOnly: true
type:
allOf:
- $ref: '#/components/schemas/card_type'
- description: The payment card type.
brand:
allOf:
- $ref: '#/components/schemas/card_brand'
- description: The card brand or network. Typically used in the response.
billing_address:
allOf:
- $ref: '#/components/schemas/address_portable'
- description: >-
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.
not:
anyOf:
- required:
- address_line_3
- required:
- admin_area_3
- required:
- admin_area_4
- required:
- address_details
authentication_result:
$ref: '#/components/schemas/authentication_response'
venmo_wallet_attributes_response:
title: venmo_wallet_attributes_response
description: Additional attributes associated with the use of a Venmo Wallet.
type: object
properties:
vault:
$ref: '#/components/schemas/venmo_vault_response'
account_id:
title: PayPal Account Identifier
description: The account identifier for a PayPal account.
type: string
minLength: 13
maxLength: 13
pattern: ^[2-9A-HJ-NP-Z]{13}$
money:
title: Money
description: >-
The currency and amount for a financial transaction, such as a balance
or payment due.
type: object
required:
- currency_code
- value
properties:
currency_code:
$ref: '#/components/schemas/currency_code'
value:
description: >-
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](/api/rest/reference/currency-codes/).
type: string
minLength: 0
maxLength: 32
pattern: ^((-?[0-9]+)|(-?([0-9]+)?[.][0-9]+))$
amount_breakdown:
title: amount_breakdown
description: >-
The breakdown of the amount. Breakdown provides details such as total
item amount, total tax amount, shipping, handling, insurance, and
discounts, if any.
type: object
properties:
item_total:
allOf:
- $ref: '#/components/schemas/money'
- description: >-
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.
shipping:
allOf:
- $ref: '#/components/schemas/money'
- description: >-
The shipping fee for all items within a given `purchase_unit`.
shipping.value can not be a negative number.
handling:
allOf:
- $ref: '#/components/schemas/money'
- description: >-
The handling fee for all items within a given `purchase_unit`.
handling.value can not be a negative number.
tax_total:
allOf:
- $ref: '#/components/schemas/money'
- description: >-
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.
insurance:
allOf:
- $ref: '#/components/schemas/money'
- description: >-
The insurance fee for all items within a given `purchase_unit`.
insurance.value can not be a negative number.
shipping_discount:
allOf:
- $ref: '#/components/schemas/money'
- description: >-
The shipping discount for all items within a given
`purchase_unit`. shipping_discount.value can not be
a negative number.
discount:
allOf:
- $ref: '#/components/schemas/discount_with_breakdown'
- description: >-
The discount for all items within a given `purchase_unit`.
discount.value can not be a negative number.
payee_base:
title: payee_base
description: >-
The details for the merchant who receives the funds and fulfills the
order. The merchant is also known as the payee.
type: object
properties:
email_address:
allOf:
- $ref: '#/components/schemas/email'
- description: The email address of merchant.
merchant_id:
allOf:
- $ref: '#/components/schemas/account_id'
- description: The encrypted PayPal account ID of the merchant.
platform_fee:
title: platform_fee
description: >-
The platform or partner fee, commission, or brokerage fee that is
associated with the transaction. Not a separate or isolated transaction
leg from the external perspective. The platform fee is limited in scope
and is always associated with the original payment for the purchase
unit.
type: object
required:
- amount
properties:
amount:
allOf:
- $ref: '#/components/schemas/money'
- title: amount
description: The fee for this transaction.
payee:
allOf:
- $ref: '#/components/schemas/payee_base'
- title: payee
description: The recipient of the fee for this transaction.
disbursement_mode:
title: disbursement_mode
description: The funds that are held on behalf of the merchant.
type: string
enum:
- INSTANT
- DELAYED
default: INSTANT
universal_product_code:
title: universal_product_code
description: The Universal Product Code of the item.
type: object
required:
- code
- type
properties:
type:
title: Universal Product Code Type
description: The Universal Product Code type.
type: string
enum:
- UPC-A
- UPC-B
- UPC-C
- UPC-D
- UPC-E
- UPC-2
- UPC-5
code:
description: The UPC product code of the item.
type: string
minLength: 6
maxLength: 17
pattern: ^[0-9]{0,17}$
order_billing_plan:
title: order_billing_plan
description: >-
Metadata for merchant-managed recurring billing plans. Valid only during
the saved payment method token or billing agreement creation.
type: object
required:
- billing_cycles
properties:
billing_cycles:
description: >-
An array of billing cycles for trial billing and regular billing. A
plan can have at most two trial cycles and only one regular cycle.
type: array
minItems: 1
maxItems: 3
items:
$ref: '#/components/schemas/billing_cycle'
setup_fee:
allOf:
- $ref: '#/components/schemas/money'
- description: >-
The setup fee for the recurring plan. Ensure its part of the
item amount.
name:
description: Name of the recurring plan.
type: string
minLength: 1
maxLength: 127
pattern: ^[A-Za-z0-9() +',.:-]+$
shipping_detail:
title: shipping_detail
description: The shipping details.
type: object
properties:
name:
allOf:
- $ref: '#/components/schemas/name'
- description: >-
The name of the person to whom to ship the items. Supports only
the `full_name` property.
not:
anyOf:
- required:
- prefix
- required:
- given_name
- required:
- surname
- required:
- middle_name
- required:
- suffix
- required:
- alternate_full_name
email_address:
allOf:
- $ref: '#/components/schemas/email_address'
- description: >-
The email address of the recipient of the shipped items, which
may belong to either the payer, or an alternate contact, for
delivery.
phone_number:
allOf:
- $ref: '#/components/schemas/phone'
- description: >-
The phone number of the recipient of the shipped items, which
may belong to either the payer, or an alternate contact, for
delivery. [Format - canonical international [E.164 numbering
plan](https://www.itu.int/rec/T-REC-E.164/en)]
not:
required:
- extension_number
type:
title: Fulfillment Type
description: >-
A classification for the method of purchase fulfillment (e.g
shipping, in-store pickup, etc). Either `type` or `options` may be
present, but not both.
type: string
enum:
- SHIPPING
- PICKUP_IN_PERSON
- PICKUP_IN_STORE
- PICKUP_FROM_PERSON
default: SHIPPING
options:
description: >-
An array of shipping options that the payee or merchant offers to
the payer to ship or pick up their items.
type: array
minItems: 0
maxItems: 30
items:
allOf:
- $ref: '#/components/schemas/shipping_option'
- title: shipping_option
description: >-
The option that the payee or merchant offers to the payer to
ship or pick up their items.
address:
allOf:
- $ref: '#/components/schemas/address_portable'
- description: >-
The address of the person to whom to ship the items. Supports
only the `address_line_1`, `address_line_2`, `admin_area_1`,
`admin_area_2`, `postal_code`, and `country_code` properties.
`admin_area_1` is required for addresses located in Argentina,
Brazil, China, Canada, India, Indonesia, Japan, Mexico,
Thailand, and the United States.
not:
anyOf:
- required:
- address_line_3
- required:
- admin_area_3
- required:
- admin_area_4
- required:
- address_details
tracker:
title: tracker
description: The tracking response on creation of tracker.
type: object
allOf:
- type: object
properties:
id:
description: The tracker id.
type: string
minLength: 0
maxLength: 2147483647
pattern: ^[\S\s]*$
readOnly: true
status:
$ref: '#/components/schemas/tracker_status'
items:
description: An array of details of items in the shipment.
type: array
minItems: 0
maxItems: 32767
items:
allOf:
- $ref: '#/components/schemas/tracker_item'
- title: tracker_item
description: Items in a shipment.
links:
description: An array of request-related HATEOAS links.
type: array
minItems: 0
maxItems: 32767
readOnly: true
items:
allOf:
- $ref: '#/components/schemas/link_description-2'
- title: link_description
description: >-
A request-related [HATEOAS
link](/api/rest/responses/#hateoas-links).
- $ref: '#/components/schemas/activity_timestamps'
card_supplementary_data:
title: card_supplementary_data
description: >-
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.
type: object
properties:
level_2:
$ref: '#/components/schemas/level_2_card_processing_data'
level_3:
$ref: '#/components/schemas/level_3_card_processing_data'
risk_supplementary_data:
title: risk_supplementary_data
description: >-
Additional information necessary to evaluate the risk profile of a
transaction.
type: object
properties:
customer:
$ref: '#/components/schemas/participant_metadata'
authorization_with_additional_data:
title: authorization_with_additional_data
description: >-
The authorization with additional payment details, such as risk
assessment and processor response. These details are populated only for
certain payment methods.
type: object
allOf:
- $ref: '#/components/schemas/authorization'
- type: object
properties:
processor_response:
allOf:
- $ref: '#/components/schemas/processor_response'
- description: The processor response for card transactions.
readOnly: true
capture:
title: capture
description: A captured payment.
type: object
allOf:
- $ref: '#/components/schemas/capture_status'
- type: object
properties:
id:
description: The PayPal-generated ID for the captured payment.
type: string
minLength: 0
maxLength: 2147483647
pattern: ^[\S\s]*$
readOnly: true
amount:
allOf:
- $ref: '#/components/schemas/amount_with_breakdown'
- description: The amount for this captured payment.
readOnly: true
invoice_id:
description: >-
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.
type: string
minLength: 0
maxLength: 2147483647
pattern: ^[\S\s]*$
readOnly: true
custom_id:
description: >-
The API caller-provided external ID. Used to reconcile API
caller-initiated transactions with PayPal transactions. Appears
in transaction and settlement reports.
type: string
minLength: 0
maxLength: 255
pattern: ^[\S\s]*$
network_transaction_reference:
allOf:
- $ref: '#/components/schemas/network_transaction'
seller_protection:
allOf:
- $ref: '#/components/schemas/seller_protection'
- readOnly: true
final_capture:
description: >-
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.
type: boolean
default: false
readOnly: true
seller_receivable_breakdown:
allOf:
- $ref: '#/components/schemas/seller_receivable_breakdown'
- readOnly: true
disbursement_mode:
allOf:
- $ref: '#/components/schemas/disbursement_mode'
links:
description: >-
An array of related [HATEOAS
links](/docs/api/reference/api-responses/#hateoas-links).
type: array
minItems: 0
maxItems: 32767
readOnly: true
items:
allOf:
- $ref: '#/components/schemas/link_description-2'
- title: link_description
processor_response:
allOf:
- $ref: '#/components/schemas/processor_response'
- description: >-
An object that provides additional processor information for
a direct credit card transaction.
- allOf:
- $ref: '#/components/schemas/activity_timestamps'
refund:
title: refund
description: The refund information.
type: object
allOf:
- allOf:
- $ref: '#/components/schemas/refund_status'
- title: Refund Properties
description: >-
The detailed properties of the refund transaction, including
identifiers, amounts, breakdowns, and associated metadata.
type: object
properties:
id:
description: The PayPal-generated ID for the refund.
type: string
minLength: 0
maxLength: 2147483647
pattern: ^[\S\s]*$
readOnly: true
amount:
allOf:
- $ref: '#/components/schemas/money'
- description: The amount that the payee refunded to the payer.
readOnly: true
invoice_id:
description: >-
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.
type: string
minLength: 0
maxLength: 2147483647
pattern: ^[\S\s]*$
readOnly: true
custom_id:
description: >-
The API caller-provided external ID. Used to reconcile API
caller-initiated transactions with PayPal transactions. Appears
in transaction and settlement reports.
type: string
minLength: 1
maxLength: 255
pattern: ^[A-Za-z0-9-_.,]*$
acquirer_reference_number:
description: >-
Reference ID issued for the card transaction. This ID can be
used to track the transaction across processors, card brands and
issuing banks.
type: string
minLength: 1
maxLength: 36
pattern: ^[a-zA-Z0-9]+$
note_to_payer:
description: >-
The reason for the refund. Appears in both the payer's
transaction history and the emails that the payer receives.
type: string
minLength: 0
maxLength: 2147483647
pattern: ^[\S\s]*$
readOnly: true
seller_payable_breakdown:
title: Seller Payable Breakdown
description: The breakdown of the refund.
type: object
readOnly: true
properties:
gross_amount:
allOf:
- $ref: '#/components/schemas/money'
- description: The amount that the payee refunded to the payer.
readOnly: true
paypal_fee:
allOf:
- $ref: '#/components/schemas/money'
- description: >-
The PayPal fee that was refunded to the payer in the
currency of the transaction. This fee might not match
the PayPal fee that the payee paid when the payment was
captured.
readOnly: true
paypal_fee_in_receivable_currency:
allOf:
- $ref: '#/components/schemas/money'
- description: >-
The PayPal fee that was refunded to the payer in the
receivable currency. Returned only in cases when the
receivable currency is different from transaction
currency. Example 'CNY'.
readOnly: true
net_amount:
allOf:
- $ref: '#/components/schemas/money'
- description: >-
The net amount that the payee's account is debited in
the transaction currency. The net amount is calculated
as gross_amount minus
paypal_fee minus
platform_fees.
readOnly: true
net_amount_in_receivable_currency:
allOf:
- $ref: '#/components/schemas/money'
- description: >-
The net amount that the payee's account is debited in
the receivable currency. Returned only in cases when the
receivable currency is different from transaction
currency. Example 'CNY'.
readOnly: true
platform_fees:
description: >-
An array of platform or partner fees, commissions, or
brokerage fees for the refund.
type: array
minItems: 0
maxItems: 1
items:
allOf:
- $ref: '#/components/schemas/platform_fee'
- title: platform_fee
net_amount_breakdown:
description: >-
An array of breakdown values for the net amount. Returned
when the currency of the refund is different from the
currency of the PayPal account where the payee holds their
funds.
type: array
minItems: 0
maxItems: 32767
readOnly: true
items:
allOf:
- $ref: '#/components/schemas/net_amount_breakdown_item'
- title: net_amount_breakdown_item
total_refunded_amount:
allOf:
- $ref: '#/components/schemas/money'
- description: >-
The total amount refunded from the original capture to
date. For example, if a payer makes a $100 purchase and
was refunded $20 a week ago and was refunded $30 in this
refund, the `gross_amount` is $30 for this refund and
the `total_refunded_amount` is $50.
payer:
allOf:
- $ref: '#/components/schemas/payee_base'
- description: >-
The details associated with the merchant for this
transaction.
readOnly: true
links:
description: >-
An array of related [HATEOAS
links](/docs/api/reference/api-responses/#hateoas-links).
type: array
minItems: 0
maxItems: 32767
readOnly: true
items:
allOf:
- $ref: '#/components/schemas/link_description-2'
- title: link_description
- allOf:
- $ref: '#/components/schemas/activity_timestamps'
instrument_id:
description: The identifier of the instrument.
type: string
minLength: 1
maxLength: 256
pattern: ^[A-Za-z0-9-_.+=]+$
card_attributes:
title: card_attributes
description: Additional attributes associated with the use of this card.
type: object
properties:
customer:
$ref: '#/components/schemas/card_customer'
vault:
allOf:
- $ref: '#/components/schemas/vault_instruction_base'
- description: Instruction to vault the card based on the specified strategy.
verification:
allOf:
- $ref: '#/components/schemas/card_verification'
- description: >-
Instruction to optionally verify the card based on the specified
strategy.
payment_initiator:
title: payment_initiator
description: The person or party who initiated or triggered the payment.
type: string
enum:
- CUSTOMER
- MERCHANT
stored_payment_source_payment_type:
title: stored_payment_source_payment_type
description: Indicates the type of the stored payment_source payment.
type: string
enum:
- ONE_TIME
- RECURRING
- UNSCHEDULED
stored_payment_source_usage_type:
title: stored_payment_source_usage_type
description: >-
Indicates if this is a `first` or `subsequent` payment using a stored
payment source (also referred to as stored credential or card on file).
type: string
enum:
- FIRST
- SUBSEQUENT
- DERIVED
default: DERIVED
network_transaction_reference:
title: network_transaction_reference
description: Reference values used by the card network to identify a transaction.
type: object
required:
- id
allOf:
- $ref: '#/components/schemas/network_transaction'
eci_flag:
description: >-
Electronic Commerce Indicator (ECI). The ECI value is part of the 2 data
elements that indicate the transaction was processed electronically.
This should be passed on the authorization transaction to the
Gateway/Processor.
type: string
enum:
- MASTERCARD_NON_3D_SECURE_TRANSACTION
- MASTERCARD_ATTEMPTED_AUTHENTICATION_TRANSACTION
- MASTERCARD_FULLY_AUTHENTICATED_TRANSACTION
- FULLY_AUTHENTICATED_TRANSACTION
- ATTEMPTED_AUTHENTICATION_TRANSACTION
- NON_3D_SECURE_TRANSACTION
url:
description: Describes the URL.
type: string
minLength: 0
maxLength: 2147483647
format: uri
paypal_wallet_customer:
title: paypal_wallet_customer
description: The details about a customer in PayPal's system of record.
type: object
allOf:
- $ref: '#/components/schemas/customer'
- type: object
properties:
merchant_customer_id:
description: >-
Merchants and partners may already have a data-store where their
customer information is persisted. Use merchant_customer_id to
associate the PayPal-generated customer.id to your
representation of a customer.
type: string
minLength: 1
maxLength: 64
pattern: ^[0-9a-zA-Z-_.^*$@#]+$
vault_paypal_wallet_base:
title: vault_paypal_wallet_base
description: >-
Resource consolidating common request and response attributes for
vaulting PayPal Wallet.
type: object
required:
- usage_type
allOf:
- $ref: '#/components/schemas/vault_instruction_base'
- type: object
properties:
description:
description: >-
The description displayed to PayPal consumer on the approval
flow for PayPal, as well as on the PayPal payment token
management experience on PayPal.com.
type: string
minLength: 1
maxLength: 128
pattern: ^[\S\s]*$
usage_pattern:
title: PayPal Payment Token Usage Pattern
description: Expected business/pricing model for the billing agreement.
type: string
enum:
- IMMEDIATE
- DEFERRED
- RECURRING_PREPAID
- RECURRING_POSTPAID
- THRESHOLD_PREPAID
- THRESHOLD_POSTPAID
- SUBSCRIPTION_PREPAID
- SUBSCRIPTION_POSTPAID
- UNSCHEDULED_PREPAID
- UNSCHEDULED_POSTPAID
- INSTALLMENT_PREPAID
- INSTALLMENT_POSTPAID
shipping:
allOf:
- $ref: '#/components/schemas/shipping_detail'
- description: The shipping address for the Payer.
not:
required:
- options
usage_type:
title: PayPal Payment Token Usage Type
description: The usage type associated with the PayPal payment token.
type: string
enum:
- MERCHANT
- PLATFORM
customer_type:
title: PayPal Payment Token Customer Type
description: >-
The customer type associated with the PayPal payment token. This
is to indicate whether the customer acting on the merchant /
platform is either a business or a consumer.
type: string
enum:
- CONSUMER
- BUSINESS
default: CONSUMER
permit_multiple_payment_tokens:
description: >-
Create multiple payment tokens for the same payer,
merchant/platform combination. Use this when the customer has
not logged in at merchant/platform. The payment token thus
generated, can then also be used to create the customer account
at merchant/platform. Use this also when multiple payment tokens
are required for the same payer, different customer at
merchant/platform. This helps to identify customers distinctly
even though they may share the same PayPal account. This only
applies to PayPal payment source.
type: boolean
default: false
language:
description: >-
The [language tag](https://tools.ietf.org/html/bcp47#section-2) for the
language in which to localize the error-related strings, such as
messages, issues, and suggested actions. The tag is made up of the [ISO
639-2 language
code](https://www.loc.gov/standards/iso639-2/php/code_list.php), the
optional [ISO-15924 script
tag](https://www.unicode.org/iso15924/codelists.html), and the [ISO-3166
alpha-2 country code](/api/rest/reference/country-codes/) or [M49 region
code](https://unstats.un.org/unsd/methodology/m49/).
type: string
minLength: 2
maxLength: 10
pattern: ^[a-z]{2}(?:-[A-Z][a-z]{3})?(?:-(?:[A-Z]{2}|[0-9]{3}))?$
app_switch_context:
title: Merchant App Switch Details & Preferences
description: >-
Merchant provided details of the native app or mobile web browser to
facilitate buyer's app switch to the PayPal consumer app.
type: object
properties:
native_app:
$ref: '#/components/schemas/native_app_context'
mobile_web:
$ref: '#/components/schemas/mobile_web_context'
callback_configuration:
title: callback_configuration
description: CallBack Configuration that the merchant can provide to PayPal/Venmo.
type: object
required:
- callback_events
- callback_url
properties:
callback_events:
description: >-
An array of callback events merchant can subscribe to for the
corresponding callback url.
type: array
minItems: 1
maxItems: 5
uniqueItems: true
items:
title: callback events
description: CallBack event.
type: string
enum:
- SHIPPING_ADDRESS
- SHIPPING_OPTIONS
callback_url:
description: >-
Merchant provided CallBack url.PayPal/Venmo will use this url to
call the merchant back when the events occur .PayPal/Venmo expects a
secured url usually in the https format.merchant can append the cart
id or other params part of the url as query or path params.
type: string
minLength: 10
maxLength: 2040
format: uri
charge_pattern:
description: Expected business/pricing model for the billing agreement.
type: string
enum:
- IMMEDIATE
- DEFERRED
- RECURRING_PREPAID
- RECURRING_POSTPAID
- THRESHOLD_PREPAID
- THRESHOLD_POSTPAID
- SUBSCRIPTION_PREPAID
- SUBSCRIPTION_POSTPAID
- UNSCHEDULED_PREPAID
- UNSCHEDULED_POSTPAID
- INSTALLMENT_PREPAID
- INSTALLMENT_POSTPAID
ip_address:
title: IP Address
description: >-
An Internet Protocol address (IP address). This address assigns a
numerical label to each device that is connected to a computer network
through the Internet Protocol. Supports IPv4 and IPv6 addresses.
type: string
minLength: 7
maxLength: 39
pattern: >-
^(([0-9]|[1-9][0-9]|1[0-9]{2}|2[0-4][0-9]|25[0-5])\.){3}([0-9]|[1-9][0-9]|1[0-9]{2}|2[0-4][0-9]|25[0-5])$|^(([a-zA-Z]|[a-zA-Z][a-zA-Z0-9\-]*[a-zA-Z0-9])\.)*([A-Za-z]|[A-Za-z][A-Za-z0-9\-]*[A-Za-z0-9])$|^\s*((([0-9A-Fa-f]{1,4}:){7}([0-9A-Fa-f]{1,4}|:))|(([0-9A-Fa-f]{1,4}:){6}(:[0-9A-Fa-f]{1,4}|((25[0-5]|2[0-4]\d|1\d\d|[1-9]?\d)(\.(25[0-5]|2[0-4]\d|1\d\d|[1-9]?\d)){3})|:))|(([0-9A-Fa-f]{1,4}:){5}(((:[0-9A-Fa-f]{1,4}){1,2})|:((25[0-5]|2[0-4]\d|1\d\d|[1-9]?\d)(\.(25[0-5]|2[0-4]\d|1\d\d|[1-9]?\d)){3})|:))|(([0-9A-Fa-f]{1,4}:){4}(((:[0-9A-Fa-f]{1,4}){1,3})|((:[0-9A-Fa-f]{1,4})?:((25[0-5]|2[0-4]\d|1\d\d|[1-9]?\d)(\.(25[0-5]|2[0-4]\d|1\d\d|[1-9]?\d)){3}))|:))|(([0-9A-Fa-f]{1,4}:){3}(((:[0-9A-Fa-f]{1,4}){1,4})|((:[0-9A-Fa-f]{1,4}){0,2}:((25[0-5]|2[0-4]\d|1\d\d|[1-9]?\d)(\.(25[0-5]|2[0-4]\d|1\d\d|[1-9]?\d)){3}))|:))|(([0-9A-Fa-f]{1,4}:){2}(((:[0-9A-Fa-f]{1,4}){1,5})|((:[0-9A-Fa-f]{1,4}){0,3}:((25[0-5]|2[0-4]\d|1\d\d|[1-9]?\d)(\.(25[0-5]|2[0-4]\d|1\d\d|[1-9]?\d)){3}))|:))|(([0-9A-Fa-f]{1,4}:){1}(((:[0-9A-Fa-f]{1,4}){1,6})|((:[0-9A-Fa-f]{1,4}){0,4}:((25[0-5]|2[0-4]\d|1\d\d|[1-9]?\d)(\.(25[0-5]|2[0-4]\d|1\d\d|[1-9]?\d)){3}))|:))|(:(((:[0-9A-Fa-f]{1,4}){1,7})|((:[0-9A-Fa-f]{1,4}){0,5}:((25[0-5]|2[0-4]\d|1\d\d|[1-9]?\d)(\.(25[0-5]|2[0-4]\d|1\d\d|[1-9]?\d)){3}))|:)))(%.+)?\s*$
apple_pay_payment_data:
title: apple_pay_payment_data
description: >-
Information about the decrypted apple pay payment data for the token
like cryptogram, eci indicator.
type: object
properties:
cryptogram:
description: >-
Online payment cryptogram, as defined by 3D Secure. The pattern is
defined by an external party and supports Unicode.
type: string
minLength: 1
maxLength: 2000
pattern: ^.*$
eci_indicator:
description: >-
ECI indicator, as defined by 3- Secure. The pattern is defined by an
external party and supports Unicode.
type: string
minLength: 1
maxLength: 256
pattern: ^.*$
emv_data:
description: >-
Encoded Apple Pay EMV Payment Structure used for payments in China.
The pattern is defined by an external party and supports Unicode.
type: string
minLength: 1
maxLength: 2000
pattern: ^.*$
pin:
description: >-
Bank Key encrypted Apple Pay PIN. The pattern is defined by an
external party and supports Unicode.
type: string
minLength: 1
maxLength: 2000
pattern: ^.*$
customer:
title: customer
description: >-
This object represents a merchant’s customer, allowing them to store
contact details, and track all payments associated with the same
customer.
type: object
properties:
id:
$ref: '#/components/schemas/merchant_partner_customer_id'
email_address:
allOf:
- $ref: '#/components/schemas/email'
- description: >-
Email address of the customer as provided to the merchant or on
file with the merchant. Email Address is required if you are
processing the transaction using PayPal Guest Processing which
is offered to select partners and merchants.
phone:
allOf:
- $ref: '#/components/schemas/phone_with_type'
- description: >-
The phone number of the customer as provided to the merchant or
on file with the merchant. The `phone.phone_number` supports
only `national_number`.
name:
allOf:
- $ref: '#/components/schemas/name'
- description: >-
The full name of the customer as provided to the merchant or on
file with the merchant.
not:
anyOf:
- required:
- prefix
- required:
- middle_name
- required:
- suffix
- required:
- alternate_full_name
- required:
- full_name
v3_vault_instruction_base:
title: v3_vault_instruction_base
description: >-
Base vaulting specification. The object can be extended for specific use
cases within each payment_source that supports vaulting.
type: object
required:
- store_in_vault
properties:
store_in_vault:
$ref: '#/components/schemas/store_in_vault_instruction'
venmo_wallet_customer:
title: venmo_wallet_customer
description: >-
This object represents a merchant’s customer, allowing them to store
contact details, and track all payments associated with the same
customer.
type: object
allOf:
- $ref: '#/components/schemas/customer'
- type: object
vault_venmo_wallet_base:
title: vault_Venmo_wallet_base
description: >-
Resource consolidating common request and response attirbutes for
vaulting Venmo Wallet.
type: object
required:
- usage_type
allOf:
- $ref: '#/components/schemas/v3_vault_instruction_base'
- type: object
properties:
description:
description: >-
The description displayed to Venmo consumer on the approval flow
for Venmo, as well as on the Venmo payment token management
experience on Venmo.com.
type: string
minLength: 1
maxLength: 128
pattern: ^[a-zA-Z0-9_'\-., :;\!?"]*$
usage_pattern:
title: Venmo Payment Token Usage Pattern
description: Expected business/pricing model for the billing agreement.
type: string
enum:
- IMMEDIATE
- DEFERRED
- RECURRING_PREPAID
- RECURRING_POSTPAID
- THRESHOLD_PREPAID
- THRESHOLD_POSTPAID
usage_type:
title: Venmo Payment Token Usage Type
description: The usage type associated with the Venmo payment token.
type: string
enum:
- MERCHANT
- PLATFORM
customer_type:
title: Venmo Payment Token Customer Type
description: >-
The customer type associated with the Venmo payment token. This
is to indicate whether the customer acting on the merchant /
platform is either a business or a consumer.
type: string
enum:
- CONSUMER
- BUSINESS
default: CONSUMER
permit_multiple_payment_tokens:
description: >-
Create multiple payment tokens for the same payer,
merchant/platform combination. Use this when the customer has
not logged in at merchant/platform. The payment token thus
generated, can then also be used to create the customer account
at merchant/platform. Use this also when multiple payment tokens
are required for the same payer, different customer at
merchant/platform. This helps to identify customers distinctly
even though they may share the same Venmo account.
type: boolean
default: false
liability_shift:
title: liability_shift
description: Liability shift indicator. The outcome of the issuer's authentication.
type: string
enum:
- 'NO'
- POSSIBLE
- UNKNOWN
three_d_secure_authentication_response:
title: three_d_secure_authentication_response
description: Results of 3D Secure Authentication.
type: object
properties:
authentication_status:
allOf:
- $ref: '#/components/schemas/pares_status'
- description: The outcome of the issuer's authentication.
enrollment_status:
allOf:
- $ref: '#/components/schemas/enrolled'
- description: Status of authentication eligibility.
card_vault_response:
title: card_vault_response
description: The details about a saved Card payment source.
type: object
allOf:
- allOf:
- $ref: '#/components/schemas/vault_response'
- not:
required:
- customer
- type: object
properties:
customer:
allOf:
- $ref: '#/components/schemas/card_customer'
paypal_wallet_vault_response:
title: paypal_wallet_vault_response
description: The details about a saved PayPal Wallet payment source.
type: object
allOf:
- allOf:
- $ref: '#/components/schemas/vault_response'
- not:
required:
- customer
- type: object
properties:
customer:
$ref: '#/components/schemas/paypal_wallet_customer'
cobranded_card:
title: cobranded_card
description: Details about the merchant cobranded card used for order purchase.
type: object
properties:
labels:
description: Array of labels for the cobranded card.
type: array
minItems: 1
maxItems: 25
items:
title: label
description: Label for the cobranded card.
type: string
minLength: 1
maxLength: 256
pattern: ^[\S\s]*$
payee:
allOf:
- $ref: '#/components/schemas/payee_base'
- title: payee
description: Merchant associated with the purchase.
not:
required:
- client_id
amount:
allOf:
- $ref: '#/components/schemas/money'
- description: Amount that was charged to the cobranded card.
vault_response:
title: vault_response
description: The details about a saved payment source.
type: object
properties:
id:
description: The PayPal-generated ID for the saved payment source.
type: string
minLength: 1
maxLength: 255
pattern: ^[\S\s]*$
status:
title: Vault Status
description: The vault status.
type: string
enum:
- VAULTED
- CREATED
- APPROVED
customer:
allOf:
- $ref: '#/components/schemas/customer'
- not:
anyOf:
- required:
- email_address
- required:
- phone
links:
description: An array of request-related HATEOAS links.
type: array
minItems: 1
maxItems: 10
readOnly: true
items:
allOf:
- $ref: '#/components/schemas/link_description'
- title: link_description
description: >-
A request-related [HATEOAS
link](/docs/api/reference/api-responses/#hateoas-links).
venmo_vault_response:
title: venmo_vault_response
description: The details about a saved venmo payment source.
type: object
allOf:
- allOf:
- $ref: '#/components/schemas/vault_response'
- not:
required:
- customer
- type: object
properties:
customer:
allOf:
- $ref: '#/components/schemas/venmo_wallet_customer'
currency_code:
description: >-
The [three-character ISO-4217 currency
code](/api/rest/reference/currency-codes/) that identifies the currency.
type: string
minLength: 3
maxLength: 3
pattern: ^[\S\s]*$
discount_with_breakdown:
title: discount_with_breakdown
description: >-
The discount amount and currency code. For list of supported currencies
and decimal precision, see the PayPal REST APIs Currency Codes.
type: object
allOf:
- $ref: '#/components/schemas/money'
- type: object
billing_cycle:
title: billing_cycle
description: >-
The billing cycle providing details of the billing frequency, amount,
duration and if the billing cycle is a free, discounted or regular
billing cycle. The sequence of the billing cycle will be in the
following order - free trial billing cycle(s), discounted trial billing
cycle(s), regular billing cycle(s).
type: object
required:
- tenure_type
properties:
tenure_type:
description: >-
The tenure type of the billing cycle identifies if the billing cycle
is a trial(free or discounted) or regular billing cycle.
type: string
enum:
- REGULAR
- TRIAL
pricing_scheme:
allOf:
- $ref: '#/components/schemas/pricing_scheme'
- description: >-
The active pricing scheme for this billing cycle. A free trial
billing cycle does not require a pricing scheme.
total_cycles:
description: >-
The number of times this billing cycle gets executed. Trial billing
cycles can only be executed a finite number of times (value between
1 and 999 for total_cycles).
Regular billing cycles can be executed infinite times (value of
0 for total_cycles) or a finite number of
times (value between 1 and 999 for
total_cycles).
type: integer
minimum: 0
maximum: 999
default: 1
sequence:
description: >-
The order in which this cycle is to run among other billing cycles.
For example, a trial billing cycle has a `sequence` of `1` while a
regular billing cycle has a `sequence` of `2`, so that trial cycle
runs before the regular cycle.
type: integer
minimum: 1
maximum: 3
default: 1
start_date:
allOf:
- $ref: '#/components/schemas/date_no_time'
- description: >-
The start date for the billing cycle, in YYYY-MM-DD. This field
should be not be provided if the billing cycle starts at the
time of checkout. When this field is not provided, the billing
cycle amount will be included in any data validations confirming
that the total provided by the merchant match the sum of
individual items due at the time of checkout. Only one billing
cycle (with sequence equal to 1) can have a no start date.
shipping_option:
title: shipping_option
description: >-
The options that the payee or merchant offers to the payer to ship or
pick up their items.
type: object
required:
- id
- label
- selected
properties:
id:
description: A unique ID that identifies a payer-selected shipping option.
type: string
minLength: 0
maxLength: 127
pattern: ^[\S\s]*$
label:
description: >-
A description that the payer sees, which helps them choose an
appropriate shipping option. For example, `Free Shipping`, `USPS
Priority Shipping`, `Expédition prioritaire USPS`, or `USPS yōuxiān
fā huò`. Localize this description to the payer's locale.
type: string
minLength: 0
maxLength: 127
pattern: ^[\S\s]*$
type:
allOf:
- $ref: '#/components/schemas/shipping_type'
- description: A classification for the method of purchase fulfillment.
amount:
allOf:
- $ref: '#/components/schemas/money'
- description: The shipping cost for the selected option.
selected:
description: >-
If the API request sets `selected = true`, it represents the
shipping option that the payee or merchant expects to be
pre-selected for the payer when they first view the
`shipping.options` in the PayPal Checkout experience. As part of the
response if a `shipping.option` contains `selected=true`, it
represents the shipping option that the payer selected during the
course of checkout with PayPal. Only one `shipping.option` can be
set to `selected=true`.
type: boolean
tracker_status:
title: Tracker Status
description: The status of the item shipment.
type: string
enum:
- CANCELLED
- SHIPPED
tracker_item:
title: tracker_item
description: The details of the items in the shipment.
type: object
properties:
name:
description: The item name or title.
type: string
minLength: 1
maxLength: 127
pattern: ^[\S\s]*$
quantity:
description: The item quantity. Must be a whole number.
type: string
minLength: 1
maxLength: 10
pattern: ^[1-9][0-9]{0,9}$
sku:
description: >-
The stock keeping unit (SKU) for the item. This can contain unicode
characters.
type: string
minLength: 1
maxLength: 127
pattern: ^[\S\s]*$
url:
description: >-
The URL to the item being purchased. Visible to buyer and used in
buyer experiences.
type: string
minLength: 1
maxLength: 2048
format: uri
image_url:
description: >-
The URL of the item's image. File type and size restrictions apply.
An image that violates these restrictions will not be honored.
type: string
minLength: 1
maxLength: 2048
format: uri
upc:
allOf:
- $ref: '#/components/schemas/universal_product_code'
- description: The Universal Product Code of the item.
level_2_card_processing_data:
title: level_2
description: >-
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.
type: object
properties:
invoice_id:
description: >-
Use this field to pass a purchase identification value of up to 127
ASCII characters. The length of this field will be adjusted to meet
network specifications (25chars for Visa and Mastercard, 17chars for
Amex), and the original invoice ID will still be displayed in your
existing reports.
type: string
minLength: 1
maxLength: 127
pattern: ^[\w‘\-.,":;\!?]*$
tax_total:
allOf:
- $ref: '#/components/schemas/money'
- description: >
Use this field to break down the amount of tax included in the
total purchase amount. The value provided here will not add to
the total purchase amount. The value can't be negative, and in
most cases, it must be greater than zero in order to qualify for
lower interchange rates.
Value, by country, is:
UK. A county.
US. A state.
Canada. A province.
Japan. A prefecture.
Switzerland. A kanton.
level_3_card_processing_data:
title: level_3
description: >-
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.
type: object
properties:
shipping_amount:
allOf:
- $ref: '#/components/schemas/money'
- description: >-
Use this field to break down the shipping cost included in the
total purchase amount. The value provided here will not add to
the total purchase amount. The value cannot be negative.
duty_amount:
allOf:
- $ref: '#/components/schemas/money'
- description: >-
Use this field to break down the duty amount included in the
total purchase amount. The value provided here will not add to
the total purchase amount. The value cannot be negative.
discount_amount:
allOf:
- $ref: '#/components/schemas/money'
- description: >-
Use this field to break down the discount amount included in the
total purchase amount. The value provided here will not add to
the total purchase amount. The value cannot be negative.
shipping_address:
allOf:
- $ref: '#/components/schemas/address_portable'
- description: >-
The address of the person to whom to ship the items. Supports
only the `address_line_1`, `address_line_2`, `admin_area_1`,
`admin_area_2`, `postal_code`, and `country_code` properties.
not:
anyOf:
- required:
- address_line_3
- required:
- admin_area_3
- required:
- admin_area_4
- required:
- address_details
ships_from_postal_code:
description: Use this field to specify the postal code of the shipping location.
type: string
minLength: 1
maxLength: 60
pattern: ^[a-zA-Z0-9_'.-]*$
line_items:
description: >-
A list of the items that were purchased with this payment. If your
merchant account has been configured for Level 3 processing this
field will be passed to the processor on your behalf.
type: array
minItems: 1
maxItems: 100
items:
allOf:
- $ref: '#/components/schemas/line_item'
- title: line_item
participant_metadata:
title: participant_metadata
description: Profile information of the sender or receiver.
type: object
properties:
ip_address:
allOf:
- $ref: '#/components/schemas/ip_address'
- description: >-
The consumer's IP address, which can be represented in either
IPv4 or IPv6 format.
authorization:
title: authorization
description: The authorized payment transaction.
type: object
allOf:
- $ref: '#/components/schemas/authorization_status'
- type: object
properties:
id:
description: The PayPal-generated ID for the authorized payment.
type: string
minLength: 0
maxLength: 2147483647
pattern: ^[\S\s]*$
readOnly: true
amount:
allOf:
- $ref: '#/components/schemas/amount_with_breakdown'
- description: The amount for this authorized payment.
readOnly: true
invoice_id:
description: >-
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.
type: string
minLength: 0
maxLength: 2147483647
pattern: ^[\S\s]*$
readOnly: true
custom_id:
description: >-
The API caller-provided external ID. Used to reconcile API
caller-initiated transactions with PayPal transactions. Appears
in transaction and settlement reports.
type: string
minLength: 0
maxLength: 255
pattern: ^[\S\s]*$
network_transaction_reference:
allOf:
- $ref: '#/components/schemas/network_transaction'
seller_protection:
allOf:
- $ref: '#/components/schemas/seller_protection'
- readOnly: true
expiration_time:
allOf:
- $ref: '#/components/schemas/date_time'
- description: >-
The date and time when the authorized payment expires, in
[Internet date and time
format](https://tools.ietf.org/html/rfc3339#section-5.6).
readOnly: true
links:
description: >-
An array of related [HATEOAS
links](/docs/api/reference/api-responses/#hateoas-links).
type: array
minItems: 0
maxItems: 32767
readOnly: true
items:
allOf:
- $ref: '#/components/schemas/link_description-2'
- title: link_description
- $ref: '#/components/schemas/activity_timestamps'
processor_response:
title: processor_response
description: >-
The processor response information for payment requests, such as direct
credit card transactions.
type: object
properties:
avs_code:
description: >-
The address verification code for Visa, Discover, Mastercard, or
American Express transactions.
type: string
enum:
- A
- B
- C
- D
- E
- F
- G
- I
- M
- 'N'
- P
- R
- S
- U
- W
- X
- 'Y'
- Z
- 'Null'
- '0'
- '1'
- '2'
- '3'
- '4'
readOnly: true
cvv_code:
description: >-
The card verification value code for for Visa, Discover, Mastercard,
or American Express.
type: string
enum:
- E
- I
- M
- 'N'
- P
- S
- U
- X
- All others
- '0'
- '1'
- '2'
- '3'
- '4'
readOnly: true
response_code:
description: Processor response code for the non-PayPal payment processor errors.
type: string
enum:
- '0000'
- 00N7
- '0100'
- '0390'
- '0500'
- '0580'
- '0800'
- '0880'
- '0890'
- '0960'
- 0R00
- '1000'
- 10BR
- '1300'
- '1310'
- '1312'
- '1317'
- '1320'
- '1330'
- '1335'
- '1340'
- '1350'
- '1352'
- '1360'
- '1370'
- '1380'
- '1382'
- '1384'
- '1390'
- '1393'
- '5100'
- '5110'
- '5120'
- '5130'
- '5135'
- '5140'
- '5150'
- '5160'
- '5170'
- '5180'
- '5190'
- '5200'
- '5210'
- '5400'
- '5500'
- '5650'
- '5700'
- '5710'
- '5800'
- '5900'
- '5910'
- '5920'
- '5930'
- '5950'
- '6300'
- '7600'
- '7700'
- '7710'
- '7800'
- '7900'
- '8000'
- '8010'
- '8020'
- '8030'
- '8100'
- '8110'
- '8220'
- '9100'
- '9500'
- '9510'
- '9520'
- '9530'
- '9540'
- '9600'
- PCNR
- PCVV
- PP06
- PPRN
- PPAD
- PPAB
- PPAE
- PPAG
- PPAI
- PPAR
- PPAU
- PPAV
- PPAX
- PPBG
- PPC2
- PPCE
- PPCO
- PPCR
- PPCT
- PPCU
- PPD3
- PPDC
- PPDI
- PPDV
- PPDT
- PPEF
- PPEL
- PPER
- PPEX
- PPFE
- PPFI
- PPFR
- PPFV
- PPGR
- PPH1
- PPIF
- PPII
- PPIM
- PPIT
- PPLR
- PPLS
- PPMB
- PPMC
- PPMD
- PPNC
- PPNL
- PPNM
- PPNT
- PPPH
- PPPI
- PPPM
- PPQC
- PPRE
- PPRF
- PPRR
- PPS0
- PPS1
- PPS2
- PPS3
- PPS4
- PPS5
- PPS6
- PPSC
- PPSD
- PPSE
- PPTE
- PPTF
- PPTI
- PPTR
- PPTT
- PPTV
- PPUA
- PPUC
- PPUE
- PPUI
- PPUP
- PPUR
- PPVC
- PPVE
- PPVT
readOnly: true
payment_advice_code:
description: >-
The declined payment transactions might have payment advice codes.
The card networks, like Visa and Mastercard, return payment advice
codes.
type: string
enum:
- '01'
- '02'
- '03'
- '04'
- '21'
- '22'
- '24'
- '25'
- '26'
- '27'
- '28'
- '29'
- '30'
- '40'
- '43'
readOnly: true
capture_status:
title: capture_status
description: The status and status details of a captured payment.
type: object
properties:
status:
title: Capture Status
description: The status of the captured payment.
type: string
enum:
- COMPLETED
- DECLINED
- PARTIALLY_REFUNDED
- PENDING
- REFUNDED
- FAILED
readOnly: true
status_details:
allOf:
- $ref: '#/components/schemas/capture_status_details'
- description: The details of the captured payment status.
readOnly: true
network_transaction:
title: network_transaction
description: Reference values used by the card network to identify a transaction.
type: object
properties:
id:
description: >-
Transaction reference id returned by the scheme. For Visa and Amex,
this is the "Tran id" field in response. For MasterCard, this is the
"BankNet reference id" field in response. For Discover, this is the
"NRID" field in response. The pattern we expect for this field from
Visa/Amex/CB/Discover is numeric, Mastercard/BNPP is alphanumeric
and Paysecure is alphanumeric with special character -.
type: string
minLength: 9
maxLength: 36
pattern: ^[a-zA-Z0-9-_@.:&+=*^'~#!$%()]+$
date:
description: >-
The date that the transaction was authorized by the scheme. This
field may not be returned for all networks. MasterCard refers to
this field as "BankNet reference date". For some specific networks,
such as MasterCard and Discover, this date field is mandatory when
the `previous_network_transaction_reference_id` is passed.
type: string
minLength: 4
maxLength: 4
pattern: ^[0-9]+$
network:
allOf:
- $ref: '#/components/schemas/card_brand'
- description: >-
Name of the card network through which the transaction was
routed.
acquirer_reference_number:
description: >-
Reference ID issued for the card transaction. This ID can be used to
track the transaction across processors, card brands and issuing
banks.
type: string
minLength: 1
maxLength: 36
pattern: ^[a-zA-Z0-9]+$
seller_protection:
title: seller_protection
description: >-
The level of protection offered as defined by [PayPal Seller Protection
for
Merchants](https://www.paypal.com/us/webapps/mpp/security/seller-protection).
type: object
properties:
status:
title: Seller Protection Status
description: >-
Indicates whether the transaction is eligible for seller protection.
For information, see [PayPal Seller Protection for
Merchants](https://www.paypal.com/us/webapps/mpp/security/seller-protection).
type: string
enum:
- ELIGIBLE
- PARTIALLY_ELIGIBLE
- NOT_ELIGIBLE
readOnly: true
dispute_categories:
description: An array of conditions that are covered for the transaction.
type: array
minItems: 0
maxItems: 32767
readOnly: true
items:
title: dispute_category
description: The condition that is covered for the transaction.
type: string
enum:
- ITEM_NOT_RECEIVED
- UNAUTHORIZED_TRANSACTION
seller_receivable_breakdown:
title: Seller Receivable Breakdown
description: >-
The detailed breakdown of the capture activity. This is not available
for transactions that are in pending state.
type: object
required:
- gross_amount
properties:
gross_amount:
allOf:
- $ref: '#/components/schemas/money'
- description: >-
The amount for this captured payment in the currency of the
transaction.
paypal_fee:
allOf:
- $ref: '#/components/schemas/money'
- description: >-
The applicable fee for this captured payment in the currency of
the transaction.
paypal_fee_in_receivable_currency:
allOf:
- $ref: '#/components/schemas/money'
- description: >-
The applicable fee for this captured payment in the receivable
currency. Returned only in cases the fee is charged in the
receivable currency. Example 'CNY'.
net_amount:
allOf:
- $ref: '#/components/schemas/money'
- description: >-
The net amount that the payee receives for this captured payment
in their PayPal account. The net amount is computed as
gross_amount minus the paypal_fee
minus the platform_fees.
receivable_amount:
allOf:
- $ref: '#/components/schemas/money'
- description: >-
The net amount that is credited to the payee's PayPal account.
Returned only when the currency of the captured payment is
different from the currency of the PayPal account where the
payee wants to credit the funds. The amount is computed as
net_amount times exchange_rate.
exchange_rate:
allOf:
- $ref: '#/components/schemas/exchange_rate'
- description: >-
The exchange rate that determines the amount that is credited to
the payee's PayPal account. Returned when the currency of the
captured payment is different from the currency of the PayPal
account where the payee wants to credit the funds.
platform_fees:
description: >-
An array of platform or partner fees, commissions, or brokerage fees
that associated with the captured payment.
type: array
minItems: 0
maxItems: 1
items:
allOf:
- $ref: '#/components/schemas/platform_fee'
- title: platform_fee
refund_status:
title: refund_status
description: The refund status with details.
type: object
properties:
status:
title: Refund Status With Details
description: The status of the refund.
type: string
enum:
- CANCELLED
- FAILED
- PENDING
- COMPLETED
readOnly: true
status_details:
allOf:
- $ref: '#/components/schemas/refund_status_details'
- description: The details of the refund status.
readOnly: true
net_amount_breakdown_item:
title: net_amount_breakdown
description: >-
The net amount. Returned when the currency of the refund is different
from the currency of the PayPal account where the merchant holds their
funds.
type: object
properties:
payable_amount:
allOf:
- $ref: '#/components/schemas/money'
- description: The net amount debited from the merchant's PayPal account.
readOnly: true
converted_amount:
allOf:
- $ref: '#/components/schemas/money'
- description: The converted payable amount.
readOnly: true
exchange_rate:
allOf:
- $ref: '#/components/schemas/exchange_rate'
- description: >-
The exchange rate that determines the amount that was debited
from the merchant's PayPal account.
readOnly: true
card_customer:
title: card_customer
description: The details about a customer in PayPal's system of record.
type: object
allOf:
- $ref: '#/components/schemas/customer'
- type: object
properties:
merchant_customer_id:
description: >-
Merchants and partners may already have a data-store where their
customer information is persisted. Use merchant_customer_id to
associate the PayPal-generated customer.id to your
representation of a customer.
type: string
minLength: 1
maxLength: 64
pattern: ^[0-9a-zA-Z-_.^*$@#]+$
vault_instruction_base:
title: vault_instruction_base
description: >-
Basic vault instruction specification that can be extended by specific
payment sources that supports vaulting.
type: object
properties:
store_in_vault:
$ref: '#/components/schemas/store_in_vault_instruction'
card_verification:
title: Card Verification
description: >-
The API caller can opt in to verify the card through PayPal offered
verification services (e.g. Smart Dollar Auth, 3DS).
type: object
properties:
method:
title: card_verification
description: The method used for card verification.
type: string
enum:
- SCA_ALWAYS
- SCA_WHEN_REQUIRED
- 3D_SECURE
- AVS_CVV
default: SCA_WHEN_REQUIRED
native_app_context:
title: App Switch Preferences on Native App
description: >-
Merchant provided, buyer's native app preferences to app switch to the
PayPal consumer app.
type: object
properties:
os_type:
description: Operating System type of the device that the buyer is using.
type: string
enum:
- ANDROID
- IOS
- OTHER
readOnly: true
os_version:
description: Operating System version of the device that the buyer is using.
type: string
minLength: 1
maxLength: 64
pattern: ^.*$
readOnly: true
mobile_web_context:
title: Mobile Web App Switch Context
description: >-
Buyer's mobile web browser context to app switch to the PayPal consumer
app.
type: object
properties:
return_flow:
description: >-
Merchant preference on how the buyer can navigate back to merchant
website post approving the transaction on the PayPal App.
type: string
enum:
- AUTO
- MANUAL
default: AUTO
readOnly: true
buyer_user_agent:
description: >-
User agent from the request originating from the buyer's device.
This will be used to identify the buyer's operating system and
browser versions. NOTE: Merchants must not alter or modify the
buyer's device user agent.
type: string
minLength: 1
maxLength: 512
pattern: ^.*$
merchant_partner_customer_id:
title: merchant_partner_customer_id
description: The unique ID for a customer generated by PayPal.
type: string
minLength: 1
maxLength: 22
pattern: ^[0-9a-zA-Z_-]+$
store_in_vault_instruction:
title: store_in_vault_instruction
description: Defines how and when the payment source gets vaulted.
type: string
enum:
- ON_SUCCESS
pares_status:
description: >-
Transactions status result identifier. The outcome of the issuer's
authentication.
type: string
enum:
- 'Y'
- 'N'
- U
- A
- C
- R
- D
- I
enrolled:
description: Status of Authentication eligibility.
type: string
enum:
- 'Y'
- 'N'
- U
- B
pricing_scheme:
title: pricing_scheme
description: The pricing scheme details.
type: object
required:
- pricing_model
properties:
price:
allOf:
- $ref: '#/components/schemas/money'
- description: >-
The price the customer will be charged based on the pricing
model
pricing_model:
description: The pricing model for the billing cycle.
type: string
enum:
- FIXED
- VARIABLE
- AUTO_RELOAD
reload_threshold_amount:
allOf:
- $ref: '#/components/schemas/money'
- description: >-
The threshold amount on which the reload charge would be
triggered. This will be associated with the account-balance
where if the account-balance goes below this amount then
customer would incur reload charge.
shipping_type:
title: shipping_type
description: A classification for the method of purchase fulfillment.
type: string
enum:
- SHIPPING
- PICKUP
- PICKUP_IN_STORE
- PICKUP_FROM_PERSON
default: SHIPPING
line_item:
title: line_item
description: >-
The line items for this purchase. If your merchant account has been
configured for Level 3 processing this field will be passed to the
processor on your behalf.
type: object
allOf:
- $ref: '#/components/schemas/item_without_category_tax_or_amount'
- type: object
properties:
unit_amount:
allOf:
- $ref: '#/components/schemas/money'
- description: >-
The item price or rate per unit. Must equal
unit_amount * quantity for all items.
unit_amount.value can not be a negative number.
tax:
allOf:
- $ref: '#/components/schemas/money'
- description: >-
The item tax for each unit. Must equal tax *
quantity for all items. tax.value can
not be a negative number.
commodity_code:
description: >-
Code used to classify items purchased and track the total amount
spent across various categories of products and services.
Different corporate purchasing organizations may use different
standards, but the United Nations Standard Products and Services
Code (UNSPSC) is frequently used.
type: string
minLength: 1
maxLength: 12
pattern: ^[a-zA-Z0-9_'.-]*$
discount_amount:
allOf:
- $ref: '#/components/schemas/money'
- description: >-
Use this field to break down the discount amount included in
the total purchase amount. The value provided here will not
add to the total purchase amount. The value cannot be
negative.
total_amount:
allOf:
- $ref: '#/components/schemas/money'
- description: >-
The subtotal for all items. Must equal the sum of
(items[].unit_amount * items[].quantity) for all items.
item_total.value can not be a negative number.
unit_of_measure:
description: >-
Unit of measure is a standard used to express the magnitude of a
quantity in international trade. Most commonly used (but not
limited to) examples are: Acre (ACR), Ampere (AMP), Centigram
(CGM), Centimetre (CMT), Cubic inch (INQ), Cubic metre (MTQ),
Fluid ounce (OZA), Foot (FOT), Hour (HUR), Item (ITM), Kilogram
(KGM), Kilometre (KMT), Kilowatt (KWT), Liquid gallon (GLL),
Liter (LTR), Pounds (LBS), Square foot (FTK).
type: string
minLength: 1
maxLength: 12
pattern: ^[a-zA-Z0-9_'.-]*$
authorization_status:
title: authorization_status
description: The status fields and status details for an authorized payment.
type: object
properties:
status:
title: Authorization Status
description: The status for the authorized payment.
type: string
enum:
- CREATED
- CAPTURED
- DENIED
- PARTIALLY_CAPTURED
- VOIDED
- PENDING
readOnly: true
status_details:
allOf:
- $ref: '#/components/schemas/authorization_status_details'
- description: The details of the authorized order pending status.
readOnly: true
capture_status_details:
title: capture_status_details
description: The details of the captured payment status.
type: object
properties:
reason:
title: Capture Incomplete Reason
description: The reason why the captured payment status is `PENDING` or `DENIED`.
type: string
enum:
- BUYER_COMPLAINT
- CHARGEBACK
- ECHECK
- INTERNATIONAL_WITHDRAWAL
- OTHER
- PENDING_REVIEW
- RECEIVING_PREFERENCE_MANDATES_MANUAL_ACTION
- REFUNDED
- TRANSACTION_APPROVED_AWAITING_FUNDING
- UNILATERAL
- VERIFICATION_REQUIRED
- DECLINED_BY_RISK_FRAUD_FILTERS
exchange_rate:
title: exchange_rate
description: >-
The exchange rate that determines the amount to convert from one
currency to another currency.
type: object
readOnly: true
properties:
source_currency:
allOf:
- $ref: '#/components/schemas/currency_code'
- description: The source currency from which to convert an amount.
target_currency:
allOf:
- $ref: '#/components/schemas/currency_code'
- description: The target currency to which to convert an amount.
value:
description: >-
The target currency amount. Equivalent to one unit of the source
currency. Formatted as integer or decimal value with one to 15
digits to the right of the decimal point.
type: string
minLength: 0
maxLength: 2147483647
pattern: ^[\S\s]*$
refund_status_details:
title: refund_status_details
description: The details of the refund status.
type: object
properties:
reason:
title: Refund Incomplete Reason
description: The reason why the refund has the `PENDING` or `FAILED` status.
type: string
enum:
- ECHECK
item_without_category_tax_or_amount:
title: item
description: The details for the items to be purchased.
type: object
required:
- name
- quantity
properties:
name:
description: The item name or title.
type: string
minLength: 1
maxLength: 127
pattern: ^[\S\s]*$
quantity:
description: The item quantity. Must be a whole number.
type: string
minLength: 0
maxLength: 10
pattern: ^[1-9][0-9]{0,9}$
description:
description: The detailed item description.
type: string
minLength: 0
maxLength: 2048
pattern: ^[\S\s]*$
sku:
description: The stock keeping unit (SKU) for the item.
type: string
minLength: 0
maxLength: 127
pattern: ^[\S\s]*$
url:
description: >-
The URL to the item being purchased. Visible to buyer and used in
buyer experiences.
type: string
minLength: 1
maxLength: 2048
format: uri
image_url:
description: >-
The URL of the item's image. File type and size restrictions apply.
An image that violates these restrictions will not be honored.
type: string
minLength: 1
maxLength: 2048
format: uri
upc:
allOf:
- $ref: '#/components/schemas/universal_product_code'
- description: The Universal Product Code of the item.
billing_plan:
$ref: '#/components/schemas/order_billing_plan'
authorization_status_details:
title: authorization_status_details
description: The details of the authorized payment status.
type: object
properties:
reason:
title: Authorization Incomplete Reason
description: The reason why the authorized status is `PENDING`.
type: string
enum:
- PENDING_REVIEW
- DECLINED_BY_RISK_FRAUD_FILTERS
responses:
401_error_response:
description: Unauthorized.
content:
application/json:
schema:
$ref: '#/components/schemas/error'
examples:
generic:
summary: Generic 'Unauthorized' error.
description: Example response for unauthorized request.
value:
name: AUTHENTICATION_FAILURE
debug_id: b1d1f06c7246c
message: >-
Authentication failed due to missing Authorization header, or
invalid authentication credentials.
403_error_response:
description: Forbidden.
content:
application/json:
schema:
$ref: '#/components/schemas/error'
examples:
generic:
summary: Generic 'Forbidden' error.
description: Example response for a forbidden request.
value:
name: NOT_AUTHORIZED
debug_id: b1d1f06c7246c
message: Authorization failed due to insufficient permissions.
404_error_response:
description: Not Found.
content:
application/json:
schema:
$ref: '#/components/schemas/error'
examples:
generic:
summary: Generic 'Not Found' error.
description: >-
Example response for a request to a resource that does not
exist.
value:
name: RESOURCE_NOT_FOUND
debug_id: b1d1f06c7246c
message: The specified resource does not exist.
500_error_response:
description: Internal Server Error.
content:
application/json:
schema:
$ref: '#/components/schemas/error'
examples:
generic:
summary: Generic internal server error.
description: >-
Example response for a request that fails for reasons internal
to the server.
value:
name: INTERNAL_SERVER_ERROR
debug_id: b1d1f06c7246c
message: An internal server error has occurred.
default_response:
description: Default response.
content:
application/json:
schema:
$ref: '#/components/schemas/error'
examples:
generic:
summary: Default response.
description: >-
Example catch all response, should not be encountered in
practice.
value:
name: INTERNAL_SERVER_ERROR
debug_id: b1d1f06c7246c
message: An internal server error has occurred.
securitySchemes:
Oauth2:
type: oauth2
description: Oauth 2.0 authentication
flows:
clientCredentials:
tokenUrl: https://api-m.paypal.com/v1/oauth2/token
scopes:
https://uri.paypal.com/services/payments/payment: Manage payments and checkout workflow.
https://uri.paypal.com/services/payments/payment/reference-transaction: Permission to initiate reference transaction
https://uri.paypal.com/services/payments/initiatepayment: Initiates payments and checkout workflows.
https://uri.paypal.com/services/payments/orders/deprecating-jssdk-migration-for-limited-merchants: >-
Allows client-side integration on Create, Get, Patch, Authorize &
Capture Order endpoints.
https://uri.paypal.com/services/payments/orders/client_sdk_orders_api: >-
Enables secure client-side integration on confirm payment source
endpoint
https://uri.paypal.com/services/payments/orders/provision-card: Manage card provisioning merchants.
````