> ## Documentation Index > Fetch the complete documentation index at: https://paypal-sb-staging.mintlify.site/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/checkout_orders_v2.json post /v2/checkout/orders/{id}/authorize openapi: 3.0.3 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.28' contact: {} servers: - url: https://api-m.sandbox.paypal.com description: PayPal Sandbox Environment - url: https://api-m.paypal.com description: PayPal Live Environment security: [] tags: - 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. - 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. externalDocs: url: https://developer.paypal.com/docs/api/orders/v2/ 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: - $ref: '#/components/parameters/paypal_request_id' - $ref: '#/components/parameters/prefer' - $ref: '#/components/parameters/paypal_client_metadata_id' - $ref: '#/components/parameters/id' - $ref: '#/components/parameters/paypal_auth_assertion' requestBody: content: application/json: schema: $ref: '#/components/schemas/order_authorize_request' 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' '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' '400': description: >- Request is not well-formed, syntactically incorrect, or violates schema. content: application/json: schema: allOf: - $ref: '#/components/schemas/error_400' - $ref: '#/components/schemas/orders.authorize-400' '401': description: >- Authentication failed due to missing authorization header, or invalid authentication credentials. content: application/json: schema: allOf: - $ref: '#/components/schemas/error_401' - $ref: '#/components/schemas/401' '403': description: The authorized payment failed due to insufficient permissions. content: application/json: schema: allOf: - $ref: '#/components/schemas/error_403' - $ref: '#/components/schemas/orders.authorize-403' '404': description: The specified resource does not exist. content: application/json: schema: allOf: - $ref: '#/components/schemas/error_404' - $ref: '#/components/schemas/404' '422': description: >- The requested action could not be performed, semantically incorrect, or failed business validation. content: application/json: schema: allOf: - $ref: '#/components/schemas/error_422' - $ref: '#/components/schemas/orders.authorize-422' '500': description: An internal server error has occurred. content: application/json: schema: $ref: '#/components/schemas/error_500' default: $ref: '#/components/responses/default' 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_request_id: name: PayPal-Request-Id in: header 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). required: false schema: type: string minLength: 1 maxLength: 108 prefer: name: Prefer in: header description: >- The preferred server response upon successful completion of the request. Value is: required: false schema: type: string minLength: 1 maxLength: 25 pattern: ^[a-zA-Z=,-]*$ default: return=minimal paypal_client_metadata_id: name: PayPal-Client-Metadata-Id in: header required: false schema: type: string minLength: 1 maxLength: 36 id: name: id in: path description: The ID of the order that the tracking information is associated with. required: true schema: type: string minLength: 1 maxLength: 36 pattern: ^[A-Z0-9]+$ paypal_auth_assertion: name: PayPal-Auth-Assertion in: header description: >- An API-caller-provided JSON Web Token (JWT) assertion that identifies the merchant. For details, see PayPal-Auth-Assertion. required: false schema: type: string schemas: '401': properties: details: type: array items: anyOf: - title: INVALID_ACCOUNT_STATUS properties: issue: type: string enum: - INVALID_ACCOUNT_STATUS description: type: string enum: - Account validations failed for the user. '404': properties: details: type: array items: anyOf: - title: INVALID_RESOURCE_ID properties: issue: type: string enum: - INVALID_RESOURCE_ID description: type: string enum: - >- Specified resource ID does not exist. Please check the resource ID and try again. order_authorize_request: type: object title: Order Authorize Request description: The authorization of an order request. properties: payment_source: description: The payment source definition. type: object title: Payment Source properties: card: $ref: '#/components/schemas/card_request' token: $ref: '#/components/schemas/token' paypal: $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. apple_pay: $ref: '#/components/schemas/apple_pay_request' description: >- ApplePay payment source, allows buyer to pay using ApplePay, both on Web as well as on Native. google_pay: $ref: '#/components/schemas/google_pay_request' description: Google Pay payment source, allows buyer to pay using Google Pay. venmo: $ref: '#/components/schemas/venmo_wallet_request' description: >- Information needed to indicate that Venmo is being used to fund the payment. order_authorize_response: allOf: - $ref: '#/components/schemas/activity_timestamps' - {} - properties: id: type: string description: The ID of the order. readOnly: true payment_source: type: object title: Payment Source Response description: The payment source used to fund the payment. properties: card: $ref: '#/components/schemas/card_response' paypal: $ref: '#/components/schemas/paypal_wallet_response' 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' intent: $ref: '#/components/schemas/checkout_payment_intent' processing_instruction: $ref: '#/components/schemas/processing_instruction' payer: $ref: '#/components/schemas/payer' purchase_units: $ref: '#/components/schemas/purchase_unit_list' status: $ref: '#/components/schemas/order_status' readOnly: true links: $ref: '#/components/schemas/link_description_list' - type: object title: Order Authorize Response description: The order authorize response. error_400: type: object title: Bad Request Error description: Request is not well-formed, syntactically incorrect, or violates schema. properties: name: type: string enum: - INVALID_REQUEST message: type: string enum: - >- Request is not well-formed, syntactically incorrect, or violates schema. details: type: array items: $ref: '#/components/schemas/error_details' debug_id: type: string description: The PayPal internal ID. Used for correlation purposes. links: description: >- An array of request-related [HATEOAS links](https://en.wikipedia.org/wiki/HATEOAS). type: array minItems: 0 maxItems: 10000 items: $ref: '#/components/schemas/error_link_description' orders.authorize-400: properties: details: type: array items: anyOf: - title: INVALID_COUNTRY_CODE properties: issue: type: string enum: - INVALID_COUNTRY_CODE description: type: string enum: - >- Country code is invalid. Please refer to https://developer.paypal.com/api/rest/reference/country-codes/ for a list of supported country codes. - title: INVALID_PARAMETER_VALUE properties: issue: type: string enum: - INVALID_PARAMETER_VALUE description: type: string enum: - A parameter value is not valid. - title: MISSING_REQUIRED_PARAMETER properties: issue: type: string enum: - MISSING_REQUIRED_PARAMETER description: type: string enum: - A required field / parameter is missing - title: INVALID_STRING_LENGTH properties: issue: type: string enum: - INVALID_STRING_LENGTH description: type: string enum: - The value of a field is either too short or too long - title: INVALID_PARAMETER_SYNTAX properties: issue: type: string enum: - INVALID_PARAMETER_SYNTAX description: type: string enum: - >- The value of a field does not conform to the expected format. - title: MALFORMED_REQUEST_JSON properties: issue: type: string enum: - MALFORMED_REQUEST_JSON description: type: string enum: - The request JSON is not well formed. error_401: type: object title: Unauthorized Error description: >- Authentication failed due to missing Authorization header, or invalid authentication credentials. properties: name: type: string enum: - AUTHENTICATION_FAILURE message: type: string enum: - >- Authentication failed due to missing authorization header, or invalid authentication credentials. details: type: array items: $ref: '#/components/schemas/error_details' debug_id: type: string description: The PayPal internal ID. Used for correlation purposes. links: description: >- An array of request-related [HATEOAS links](https://en.wikipedia.org/wiki/HATEOAS). type: array minItems: 0 maxItems: 10000 items: $ref: '#/components/schemas/error_link_description' error_403: type: object title: Not Authorized Error description: >- The client is not authorized to access this resource, although it may have valid credentials. properties: name: type: string enum: - NOT_AUTHORIZED message: type: string enum: - Authorization failed due to insufficient permissions. details: type: array items: $ref: '#/components/schemas/error_details' debug_id: type: string description: The PayPal internal ID. Used for correlation purposes. links: description: >- An array of request-related [HATEOAS links](https://en.wikipedia.org/wiki/HATEOAS). type: array minItems: 0 maxItems: 10000 items: $ref: '#/components/schemas/error_link_description' orders.authorize-403: properties: details: type: array items: anyOf: - title: NOT_ELIGIBLE_FOR_TOKEN_PROCESSING properties: issue: type: string enum: - NOT_ELIGIBLE_FOR_TOKEN_PROCESSING description: type: string enum: - >- API caller is not enabled to process payments with the specified type of token. Please contact customer support to request permissions to process transactions with this type of token. - title: PERMISSION_DENIED properties: issue: type: string enum: - PERMISSION_DENIED description: type: string enum: - >- You do not have permission to access or perform operations on this resource. - title: PERMISSION_DENIED_FOR_DONATION_ITEMS properties: issue: type: string enum: - PERMISSION_DENIED_FOR_DONATION_ITEMS description: type: string enum: - >- The API Caller or Payee have not been granted appropriate permissions to send 'items.category' as 'DONATION'. Please speak to your account manager if you want to process these type of items. error_404: type: object title: Not found Error description: >- The server has not found anything matching the request URI. This either means that the URI is incorrect or the resource is not available. properties: name: type: string enum: - RESOURCE_NOT_FOUND message: type: string enum: - The specified resource does not exist. details: type: array items: $ref: '#/components/schemas/error_details' debug_id: type: string description: The PayPal internal ID. Used for correlation purposes. links: description: >- An array of request-related [HATEOAS links](https://en.wikipedia.org/wiki/HATEOAS). type: array minItems: 0 maxItems: 10000 items: $ref: '#/components/schemas/error_link_description' error_422: type: object title: Unprocessable Entity Error description: >- The requested action cannot be performed and may require interaction with APIs or processes outside of the current request. This is distinct from a 500 response in that there are no systemic problems limiting the API from performing the request. properties: name: type: string enum: - UNPROCESSABLE_ENTITY message: type: string enum: - >- The requested action could not be performed, semantically incorrect, or failed business validation. details: type: array items: $ref: '#/components/schemas/error_details' debug_id: type: string description: The PayPal internal ID. Used for correlation purposes. links: description: >- An array of request-related [HATEOAS links](https://en.wikipedia.org/wiki/HATEOAS). type: array minItems: 0 maxItems: 10000 items: $ref: '#/components/schemas/error_link_description' orders.authorize-422: properties: details: type: array items: anyOf: - title: ACTION_DOES_NOT_MATCH_INTENT properties: issue: type: string enum: - ACTION_DOES_NOT_MATCH_INTENT description: type: string enum: - >- Order was created with an intent to 'CAPTURE'. Please use v2/checkout/orders/order_id/capture to complete the transaction or alternately Create an order with an intent of 'AUTHORIZE'. - title: PREFERRED_BRAND_NOT_SUPPORTED properties: issue: type: string enum: - PREFERRED_BRAND_NOT_SUPPORTED description: type: string enum: - >- Processing of this preferred brand is not supported. Please use another brand preference to continue with this transaction. - title: AGREEMENT_ALREADY_CANCELLED properties: issue: type: string enum: - AGREEMENT_ALREADY_CANCELLED description: type: string enum: - The requested agreement is already canceled. - title: BILLING_AGREEMENT_NOT_FOUND properties: issue: type: string enum: - BILLING_AGREEMENT_NOT_FOUND description: type: string enum: - The requested Billing Agreement token was not found. - title: MISSING_PREVIOUS_REFERENCE properties: issue: type: string enum: - MISSING_PREVIOUS_REFERENCE description: type: string enum: - >- For Merchant initiated network token transactions, either the payment_source.card.stored_credential.previous_network_transaction_reference or payment_source.card.stored_credential.previous_transaction_reference must be included in the request. - title: MISSING_CRYPTOGRAM properties: issue: type: string enum: - MISSING_CRYPTOGRAM description: type: string enum: - >- Cryptogram is mandatory for any customer initiated network token transactions. - title: CARD_BRAND_NOT_SUPPORTED properties: issue: type: string enum: - CARD_BRAND_NOT_SUPPORTED description: type: string enum: - >- Processing of this card brand is not supported. Please use another card to continue with this transaction. - title: CARD_COUNTRY_NOT_SUPPORTED properties: issue: type: string enum: - CARD_COUNTRY_NOT_SUPPORTED description: type: string enum: - >- The country in which this card was issued is not currently supported. Please use another card to continue with this transaction. - title: CARD_DATA_NOT_FOUND properties: issue: type: string enum: - CARD_DATA_NOT_FOUND description: type: string enum: - >- The card issuer data information could not be retrieved. Please use a different card to proceed with this transaction. - title: DECLINED_DUE_TO_RELATED_TXN properties: issue: type: string enum: - DECLINED_DUE_TO_RELATED_TXN description: type: string enum: - >- One or more transactions in this Order did not succeed. Since this Order is being processed as an All or None Order, if one or more transactions in this Order do not succeed, then all purchase units are marked declined and will not be processed. - title: DOMESTIC_TRANSACTION_REQUIRED properties: issue: type: string enum: - DOMESTIC_TRANSACTION_REQUIRED description: type: string enum: - >- This transaction requires the payee and payer to be resident in the same country, a domestic transaction is required to create this payment. - title: DUPLICATE_INVOICE_ID properties: issue: type: string enum: - DUPLICATE_INVOICE_ID description: type: string enum: - >- Duplicate Invoice ID detected. To avoid a potential duplicate transaction your account setting requires that Invoice Id be unique for each transaction. - title: ORDER_NOT_APPROVED properties: issue: type: string enum: - ORDER_NOT_APPROVED description: type: string enum: - >- Payer has not yet approved the Order for payment. Please redirect the payer to the 'rel':'approve' url returned as part of the HATEOAS links within the Create Order call. - title: MAX_NUMBER_OF_PAYMENT_ATTEMPTS_EXCEEDED properties: issue: type: string enum: - MAX_NUMBER_OF_PAYMENT_ATTEMPTS_EXCEEDED description: type: string enum: - >- You have exceeded the maximum number of payment attempts. - title: PAYEE_BLOCKED_TRANSACTION properties: issue: type: string enum: - PAYEE_BLOCKED_TRANSACTION description: type: string enum: - >- Declined by fraud tool (Fraud Protection/Chargeback Protection) due to potential fraud risk. Please review your fraud settings. - title: CONTINGENCY_NOT_SUCCESSFUL properties: issue: type: string enum: - CONTINGENCY_NOT_SUCCESSFUL description: type: string enum: - >- 3D-Secure payer authentication is unsuccessful, so the payment cannot be completed. - title: PAYEE_FX_RATE_ID_EXPIRED properties: issue: type: string enum: - PAYEE_FX_RATE_ID_EXPIRED description: type: string enum: - >- The specified FX Rate ID has expired. Please specify a different FX Rate Id and try the request again. Alternately, remove the FX Rate ID to process the request using the default exchange rate. - title: UNSUPPORTED_INTENT_FOR_PAYMENT_SOURCE properties: issue: type: string enum: - UNSUPPORTED_INTENT_FOR_PAYMENT_SOURCE description: type: string enum: - >- `intent=AUTHORIZE` is not supported for the specified payment_source. Only `intent=CAPTURE` is supported. - title: INELIGIBLE_SHIPPING_OPTION properties: issue: type: string enum: - INELIGIBLE_SHIPPING_OPTION description: type: string enum: - >- One or more shipping options cannot be used in conjunction with this Order. - title: PAYER_ACCOUNT_LOCKED_OR_CLOSED properties: issue: type: string enum: - PAYER_ACCOUNT_LOCKED_OR_CLOSED description: type: string enum: - The payer account cannot be used for this transaction. - title: PAYER_ACCOUNT_RESTRICTED properties: issue: type: string enum: - PAYER_ACCOUNT_RESTRICTED description: type: string enum: - PAYER_ACCOUNT_RESTRICTED - title: PAYMENT_ORIGIN_NOT_ENABLED properties: issue: type: string enum: - PAYMENT_ORIGIN_NOT_ENABLED description: type: string enum: - >- The API caller account or payee is not enabled for the given 'payment_origin' option. Please contact customer support for assistance. - title: PAYER_CANNOT_PAY properties: issue: type: string enum: - PAYER_CANNOT_PAY description: type: string enum: - >- Payer cannot pay for this transaction. Please contact the payer to find other ways to pay for this transaction. - title: PAYPAL_TRANSACTION_ID_EXPIRED properties: issue: type: string enum: - PAYPAL_TRANSACTION_ID_EXPIRED description: type: string enum: - >- Specified `paypal_transaction_id` has expired. PayPal transaction ID expires 4 years after the date of the initial transaction. - title: PNREF_EXPIRED properties: issue: type: string enum: - PNREF_EXPIRED description: type: string enum: - >- Specified `pnref` has expired. PNREF expires 15 months after the date of the initial transaction. - title: PAYMENT_DENIED properties: issue: type: string enum: - PAYMENT_DENIED description: type: string enum: - PayPal has declined to process this transaction. - title: REFERENCED_CARD_EXPIRED properties: issue: type: string enum: - REFERENCED_CARD_EXPIRED description: type: string enum: - >- The card underlying the token has expired and hence cannot be used to process a payment. - title: TOKEN_EXPIRED properties: issue: type: string enum: - TOKEN_EXPIRED description: type: string enum: - The token is expired and cannot be used for payment. - title: TOKEN_ID_NOT_FOUND properties: issue: type: string enum: - TOKEN_ID_NOT_FOUND description: type: string enum: - >- Specified token was not found. Verify the token and try the request again. - title: TRANSACTION_LIMIT_EXCEEDED properties: issue: type: string enum: - TRANSACTION_LIMIT_EXCEEDED description: type: string enum: - Total payment amount exceeded transaction limit. - title: TRANSACTION_RECEIVING_LIMIT_EXCEEDED properties: issue: type: string enum: - TRANSACTION_RECEIVING_LIMIT_EXCEEDED description: type: string enum: - The transaction exceeds the receiver's receiving limit. - title: TRANSACTION_REFUSED properties: issue: type: string enum: - TRANSACTION_REFUSED description: type: string enum: - The request was refused. - title: ORDER_ALREADY_AUTHORIZED properties: issue: type: string enum: - ORDER_ALREADY_AUTHORIZED description: type: string enum: - >- Order already authorized.If 'intent=AUTHORIZE' only one authorization per order is allowed. - title: AUTH_CAPTURE_NOT_ENABLED properties: issue: type: string enum: - AUTH_CAPTURE_NOT_ENABLED description: type: string enum: - >- Authorization and Capture feature is not enabled for the merchant. Make sure that the recipient of the funds is a verified business account. - title: AMOUNT_CANNOT_BE_SPECIFIED properties: issue: type: string enum: - AMOUNT_CANNOT_BE_SPECIFIED description: type: string enum: - >- An authorization amount can only be specified if an Order has been saved by calling /v2/checkout/orders/{order_id}/save. Please save the order and try again. - title: AUTHORIZATION_AMOUNT_EXCEEDED properties: issue: type: string enum: - AUTHORIZATION_AMOUNT_EXCEEDED description: type: string enum: - >- Authorization amount specified exceeded allowable limit. Specify a different amount and try the request again. Alternately, contact Customer Support to increase your limits. Local regulations (e.g. in PSD2 countries) prohibit overages above the amount authorized by the payer. - title: AUTHORIZATION_CURRENCY_MISMATCH properties: issue: type: string enum: - AUTHORIZATION_CURRENCY_MISMATCH description: type: string enum: - >- The currency of the authorization should be same as that in which the Order was created and approved by the Payer. Please check the 'currency_code' and try again. - title: MAX_AUTHORIZATION_COUNT_EXCEEDED properties: issue: type: string enum: - MAX_AUTHORIZATION_COUNT_EXCEEDED description: type: string enum: - >- Maximum number of authorization allowed for the order is reached. Please contact Customer Support if you need to increase your limit. - title: ORDER_COMPLETED_OR_VOIDED properties: issue: type: string enum: - ORDER_COMPLETED_OR_VOIDED description: type: string enum: - >- Order is voided or completed and hence cannot be authorized. - title: ORDER_EXPIRED properties: issue: type: string enum: - ORDER_EXPIRED description: type: string enum: - >- Order is expired and hence cannot be authorized. Please contact Customer Support if you need to increase your order validity period. - title: INVALID_PICKUP_ADDRESS properties: issue: type: string enum: - INVALID_PICKUP_ADDRESS description: type: string enum: - >- If the 'shipping_option.type' is set as 'PICKUP' then the 'shipping_detail.name.full_name' should start with 'S2S' meaning Ship To Store. Example: 'S2S My Store'. - title: SHIPPING_ADDRESS_INVALID properties: issue: type: string enum: - SHIPPING_ADDRESS_INVALID description: type: string enum: - Provided shipping address is invalid. - title: PAYMENT_TYPE_NOT_SUPPORTED_FOR_INTENT properties: issue: type: string enum: - PAYMENT_TYPE_NOT_SUPPORTED_FOR_INTENT description: type: string enum: - >- Provided payment type not supported for order intent. Payment authorizations are supported only for order with `intent=AUTHORIZE` and payment captures are supported only for order with `intent=CAPTURE`. - title: BILLING_AGREEMENT_ID_MISMATCH properties: issue: type: string enum: - BILLING_AGREEMENT_ID_MISMATCH description: type: string enum: - >- Billing Agreement ID must exactly match the Billing Agreement ID that was provided during order creation. - title: PREFERRED_PAYMENT_SOURCE_MISMATCH properties: issue: type: string enum: - PREFERRED_PAYMENT_SOURCE_MISMATCH description: type: string enum: - >- Payment Source must exactly match the Preferred Payment Source that was provided during order creation. - title: INCOMPATIBLE_PARAMETER_VALUE properties: issue: type: string enum: - INCOMPATIBLE_PARAMETER_VALUE description: type: string enum: - >- The value of the field is incompatible/redundant with other fields in the order. - title: INVALID_PREVIOUS_TRANSACTION_REFERENCE properties: issue: type: string enum: - INVALID_PREVIOUS_TRANSACTION_REFERENCE description: type: string enum: - >- The authorization or capture referenced by `previous_transaction_reference` is not valid. This could be either because the previous_transaction_reference is not found or doesn't belong to the payee. Please use a valid `previous_transaction_reference`. - title: PREVIOUS_TRANSACTION_REFERENCE_HAS_CHARGEBACK properties: issue: type: string enum: - PREVIOUS_TRANSACTION_REFERENCE_HAS_CHARGEBACK description: type: string enum: - >- The capture referenced by `previous_transaction_reference` has a chargeback and hence cannot be used for this order. Please use a `previous_transaction_reference` which does not have a chargeback. - title: PREVIOUS_TRANSACTION_REFERENCE_VOIDED properties: issue: type: string enum: - PREVIOUS_TRANSACTION_REFERENCE_VOIDED description: type: string enum: - >- The status of authorization referenced by `previous_transaction_reference` is `VOIDED` and hence cannot be used for this order. Please use a `previous_transaction_reference` whose status is not `VOIDED`. - title: PAYMENT_SOURCE_MISMATCH properties: issue: type: string enum: - PAYMENT_SOURCE_MISMATCH description: type: string enum: - >- The `payment_source` in the request must match the `payment_source` used for the authorization or capture referenced by `previous_transaction_reference`. Please use `previous_transaction_reference` whose `payment_source` matches with the `payment_source` specified in the order. - title: MERCHANT_INITIATED_WITH_SECURITY_CODE properties: issue: type: string enum: - MERCHANT_INITIATED_WITH_SECURITY_CODE description: type: string enum: - >- `stored_payment_source.payment_initiator` = `MERCHANT` is not supported if `payment_source.card.security_code` is present in the order. `security_code` can be present in the order only when customer is the payment initiator. It is semantically incorrect to perform a merchant initiated payment with `security_code` is the order. - title: MERCHANT_INITIATED_WITH_AUTHENTICATION_RESULTS properties: issue: type: string enum: - MERCHANT_INITIATED_WITH_AUTHENTICATION_RESULTS description: type: string enum: - >- `stored_payment_source.payment_initiator` = `MERCHANT` is not supported if 3D-Secure authentication results are present in the order. 3D-Secure authentication results can be present in the order only when customer is the payment initiator. It is semantically incorrect to perform a merchant initiated payment with 3D-Secure authentication results is the order. - title: MERCHANT_INITIATED_WITH_MULTIPLE_PURCHASE_UNITS properties: issue: type: string enum: - MERCHANT_INITIATED_WITH_MULTIPLE_PURCHASE_UNITS description: type: string enum: - >- `stored_payment_source.payment_initiator` = `MERCHANT` is not supported if more than one purchase_unit is present in the Order. Merchant initiated payments are not supported from orders with more than one purchase_unit. Please retry the request with multiple Order requests (one for each purchase_unit). - title: RETURN_URL_REQUIRED properties: issue: type: string enum: - RETURN_URL_REQUIRED description: type: string enum: - >- The return url is required when attempting to vault this source. - title: CANCEL_URL_REQUIRED properties: issue: type: string enum: - CANCEL_URL_REQUIRED description: type: string enum: - >- The cancel url is required when attempting to vault this source. - title: PAYER_ACTION_REQUIRED properties: issue: type: string enum: - PAYER_ACTION_REQUIRED description: type: string enum: - >- Transaction cannot complete successfully, instruct the buyer to return to PayPal. - title: APPLE_PAY_AMOUNT_MISMATCH properties: issue: type: string enum: - APPLE_PAY_AMOUNT_MISMATCH description: type: string enum: - >- The 'amount' specified in the Order should match the amount that was viewed and authorized by the payer/buyer on Apple Pay. If the amount has changed, please redirect the buyer to authorize the order again via Apple Pay. - title: CARD_NUMBER_REQUIRED properties: issue: type: string enum: - CARD_NUMBER_REQUIRED description: type: string enum: - >- The card number is required when attempting to process payment with card. - title: CARD_EXPIRY_REQUIRED properties: issue: type: string enum: - CARD_EXPIRY_REQUIRED description: type: string enum: - >- The card expiry is required when attempting to process payment with card. - title: VAULT_INSTRUCTION_REQUIRED properties: issue: type: string enum: - VAULT_INSTRUCTION_REQUIRED description: type: string enum: - >- Vault instruction is required. Please use `vault.store_in_vault` to provide vault instruction. - title: MISMATCHED_VAULT_OWNER_ID properties: issue: type: string enum: - MISMATCHED_VAULT_OWNER_ID description: type: string enum: - >- The owner_id does not match with the API caller. Please verify that the owner_id is same as the API caller's payer id. - title: VAULT_OWNER_ID_NOT_SUPPORTED properties: issue: type: string enum: - VAULT_OWNER_ID_NOT_SUPPORTED description: type: string enum: - >- API caller is not enabled to specify the vault owner_id explicitly. Please contact account manager to enable the functionality. - title: MISMATCHED_VAULT_ID_TO_PAYMENT_SOURCE properties: issue: type: string enum: - MISMATCHED_VAULT_ID_TO_PAYMENT_SOURCE description: type: string enum: - >- The vault_id does not match the payment_source provided. Please verify that the vault_id token used refers to the matching payment_source and try again. For example, a PayPal token cannot be passed in the vault_id field in the payment_source.card object. - title: ORDER_CANNOT_BE_SAVED properties: issue: type: string enum: - ORDER_CANNOT_BE_SAVED description: type: string enum: - >- The option to save an order is only available if the `intent` is AUTHORIZE and `processing_instruction` uses one of the `ORDER_SAVED` options. For example, `intent`=AUTHORIZE, `processing_instruction`=ORDER_SAVED_EXPLICITLY. Please change the intent and/or processing_instruction` and try again. - title: SAVE_ORDER_NOT_SUPPORTED properties: issue: type: string enum: - SAVE_ORDER_NOT_SUPPORTED description: type: string enum: - >- The API caller account is setup in a way that does not allow it to be used for saving the order. This functionality is not available for PayPal Complete Payments Platform for Platforms & Marketplaces. - title: NOT_ELIGIBLE_FOR_PNREF_PROCESSING properties: issue: type: string enum: - NOT_ELIGIBLE_FOR_PNREF_PROCESSING description: type: string enum: - >- API caller is not enabled to process payments with the `pnref`. Please contact customer support to request permissions to process transactions with PNREF. - title: NOT_ELIGIBLE_FOR_PAYPAL_TRANSACTION_ID_PROCESSING properties: issue: type: string enum: - NOT_ELIGIBLE_FOR_PAYPAL_TRANSACTION_ID_PROCESSING description: type: string enum: - >- API caller is not enable to process payments using `paypal_transaction_id`. Please contact customer support to request permissions to process transactions with PayPal transaction ID. - title: PAYPAL_TRANSACTION_ID_NOT_FOUND properties: issue: type: string enum: - PAYPAL_TRANSACTION_ID_NOT_FOUND description: type: string enum: - >- Specified `paypal_transaction_id` was not found. Verify the value and try the request again. - title: PNREF_NOT_FOUND properties: issue: type: string enum: - PNREF_NOT_FOUND description: type: string enum: - >- Specified `pnref` was not found. Verify the value and try the request again. - title: INVALID_SECURITY_CODE_LENGTH properties: issue: type: string enum: - INVALID_SECURITY_CODE_LENGTH description: type: string enum: - >- The security_code length is invalid for the specified card brand. - title: REQUIRED_PARAMETER_FOR_CUSTOMER_INITIATED_PAYMENT properties: issue: type: string enum: - REQUIRED_PARAMETER_FOR_CUSTOMER_INITIATED_PAYMENT description: type: string enum: - >- This parameter is required when the customer is present. If the customer is not present, indicate so by sending payment_initiator=`MERCHANT`. For details, see Stored Credential. - title: INVALID_VAULT_ID properties: issue: type: string enum: - INVALID_VAULT_ID description: type: string enum: - The specified Vault ID is invalid or could not be found. - title: ORDER_AUTHORIZATION_IN_PROGRESS properties: issue: type: string enum: - ORDER_AUTHORIZATION_IN_PROGRESS description: type: string enum: - >- The `processing_instruction` sent with the selected `payment_source` was `ORDER_COMPLETE_ON_PAYMENT_APPROVAL`, resulting in auto-authorization. Merchant initiated authorization is not allowed. error_500: type: object title: Internal Server Error description: >- This is either a system or application error, and generally indicates that although the client appeared to provide a correct request, something unexpected has gone wrong on the server. properties: name: type: string enum: - INTERNAL_SERVER_ERROR message: type: string enum: - An internal server error occurred. debug_id: type: string description: The PayPal internal ID. Used for correlation purposes. links: description: >- An array of request-related [HATEOAS links](https://en.wikipedia.org/wiki/HATEOAS). type: array minItems: 0 maxItems: 10000 items: $ref: '#/components/schemas/error_link_description' example: name: INTERNAL_SERVER_ERROR message: An internal server error occurred. debug_id: 90957fca61718 links: - href: >- https://developer.paypal.com/api/orders/v2/#error-INTERNAL_SERVER_ERROR rel: information_link card_request: type: object 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*.
properties: name: type: string description: The card holder's name as it appears on the card. maxLength: 300 minLength: 1 pattern: ^.{1,300}$ number: type: string description: The primary account number (PAN) for the payment card. pattern: ^[0-9]{13,19}$ minLength: 13 maxLength: 19 expiry: $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: type: string 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`. pattern: ^[0-9]{3,4}$ minLength: 3 maxLength: 4 billing_address: 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 title: Portable Postal Address (Medium-Grained) properties: address_line_1: type: string 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. maxLength: 300 address_line_2: type: string description: >- The second line of the address, for example, a suite or apartment number. maxLength: 300 admin_area_2: type: string description: A city, town, or village. Smaller than `admin_area_level_1`. maxLength: 120 admin_area_1: type: string 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: maxLength: 300 postal_code: type: string 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). maxLength: 60 country_code: $ref: '#/components/schemas/country_code' required: - country_code attributes: $ref: '#/components/schemas/card_attributes' description: Additional attributes associated with the use of this card. vault_id: $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: $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: $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: $ref: '#/components/schemas/card_experience_context' token: type: object title: Token description: The tokenized payment source to fund a payment. properties: id: type: string description: The PayPal-generated ID for the token. pattern: ^[0-9a-zA-Z_-]+$ minLength: 1 maxLength: 255 type: type: string description: The tokenization method that generated the ID. minLength: 1 maxLength: 255 pattern: ^[0-9A-Z_-]+$ x-enumDescriptions: - value: BILLING_AGREEMENT description: >- The PayPal billing agreement ID. References an approved recurring payment for goods or services. enum: - BILLING_AGREEMENT required: - id - type paypal_wallet: type: object title: PayPal Wallet description: A resource that identifies a PayPal Wallet is used for payment. properties: vault_id: $ref: '#/components/schemas/vault_id' description: >- The PayPal-generated ID for the payment_source stored within the Vault. email_address: $ref: '#/components/schemas/email' description: The email address of the PayPal account holder. name: description: The name of the party. type: object title: Name properties: given_name: type: string description: When the party is a person, the party's given, or first, name. maxLength: 140 surname: type: string 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. maxLength: 140 phone: $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: $ref: '#/components/schemas/date_no_time' description: The birth date of the PayPal account holder in `YYYY-MM-DD` format. tax_info: $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: 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 title: Portable Postal Address (Medium-Grained) properties: address_line_1: type: string 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. maxLength: 300 address_line_2: type: string description: >- The second line of the address, for example, a suite or apartment number. maxLength: 300 admin_area_2: type: string description: A city, town, or village. Smaller than `admin_area_level_1`. maxLength: 120 admin_area_1: type: string 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: maxLength: 300 postal_code: type: string 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). maxLength: 60 country_code: $ref: '#/components/schemas/country_code' required: - country_code attributes: $ref: '#/components/schemas/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' apple_pay_request: type: object title: ApplePay payment request object description: Information needed to pay using ApplePay. 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: $ref: '#/components/schemas/full_name' description: Name on the account holder associated with apple pay. email_address: $ref: '#/components/schemas/email_address' description: The email address of the account holder associated with apple pay. 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 title: Phone properties: national_number: type: string 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). minLength: 1 maxLength: 14 pattern: ^[0-9]{1,14}?$ required: - national_number decrypted_token: $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: $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: type: object title: Google Pay payment request object description: Information needed to pay using Google Pay. properties: name: $ref: '#/components/schemas/full_name' description: Name on the account holder associated with Google Pay. email_address: $ref: '#/components/schemas/email_address' description: The email address of the account holder associated with Google Pay. 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 title: Phone properties: country_code: type: string 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). minLength: 1 maxLength: 3 pattern: ^[0-9]{1,3}?$ national_number: type: string 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). minLength: 1 maxLength: 14 pattern: ^[0-9]{1,14}?$ required: - country_code - national_number card: description: >- The payment card used to fund a Google Pay payment. Can be a credit or debit card. type: object title: Google Pay Card properties: name: type: string description: The card holder's name as it appears on the card. maxLength: 300 minLength: 1 pattern: ^.{1,300}$ type: $ref: '#/components/schemas/card_type' description: The payment card type. brand: $ref: '#/components/schemas/card_brand' description: The card brand or network. Typically used in the response. billing_address: 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 title: Portable Postal Address (Medium-Grained) properties: address_line_1: type: string 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. maxLength: 300 address_line_2: type: string description: >- The second line of the address, for example, a suite or apartment number. maxLength: 300 admin_area_2: type: string description: A city, town, or village. Smaller than `admin_area_level_1`. maxLength: 120 admin_area_1: type: string 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: maxLength: 300 postal_code: type: string 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). maxLength: 60 country_code: $ref: '#/components/schemas/country_code' required: - country_code decrypted_token: $ref: '#/components/schemas/google_pay_decrypted_token_data' description: The decrypted payload details for the Google Pay token. assurance_details: $ref: '#/components/schemas/assurance_details' description: >- Information about what validation has been performed on the returned payment credentials. attributes: $ref: '#/components/schemas/google_pay_attributes' experience_context: $ref: '#/components/schemas/google_pay_experience_context' venmo_wallet_request: type: object title: Venmo Wallet Request description: Information needed to pay using Venmo. properties: vault_id: $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: $ref: '#/components/schemas/email' description: The email address of the payer. experience_context: $ref: '#/components/schemas/venmo_wallet_experience_context' attributes: $ref: '#/components/schemas/venmo_wallet_attributes' description: Additional attributes associated with the use of this wallet. activity_timestamps: type: object description: >- The date and time stamps that are common to authorized payment, captured payment, and refund transactions. title: Transaction Date and Time Stamps properties: create_time: $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: $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 card_response: type: object title: Card Response description: >- The payment card to use to fund a payment. Card can be a credit or debit card. properties: name: type: string description: The card holder's name as it appears on the card. minLength: 2 maxLength: 300 last_digits: type: string description: The last digits of the payment card. pattern: '[0-9]{2,}' readOnly: true brand: $ref: '#/components/schemas/card_brand' description: The card brand or network. Typically used in the response. readOnly: true available_networks: $ref: '#/components/schemas/card_brand_list' type: $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: $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: $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: type: object title: PayPal Wallet Response description: The PayPal Wallet response. properties: email_address: $ref: '#/components/schemas/email' description: The email address of the PayPal account holder. account_id: $ref: '#/components/schemas/account_id-2' description: The PayPal-assigned ID for the PayPal account holder. readOnly: true account_status: type: string description: >- The account status indicates whether the buyer has verified the financial details associated with their PayPal account. readOnly: true minLength: 1 maxLength: 255 pattern: ^[A-Z_]+$ x-enumDescriptions: - value: VERIFIED description: >- The buyer has completed the verification of the financial details associated with this PayPal account. For example: confirming their bank account. - value: UNVERIFIED description: >- The buyer has not completed the verification of the financial details associated with this PayPal account. For example: confirming their bank account. enum: - VERIFIED - UNVERIFIED name: description: The name of the party. type: object title: Name properties: given_name: type: string description: When the party is a person, the party's given, or first, name. maxLength: 140 surname: type: string 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. maxLength: 140 phone_type: $ref: '#/components/schemas/phone_type' phone_number: $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). 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: $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: $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: 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 title: Portable Postal Address (Medium-Grained) properties: address_line_1: type: string 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. maxLength: 300 address_line_2: type: string description: >- The second line of the address, for example, a suite or apartment number. maxLength: 300 admin_area_2: type: string description: A city, town, or village. Smaller than `admin_area_level_1`. maxLength: 120 admin_area_1: type: string 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: maxLength: 300 postal_code: type: string 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). maxLength: 60 country_code: $ref: '#/components/schemas/country_code' required: - country_code attributes: $ref: '#/components/schemas/paypal_wallet_attributes_response' stored_credential: $ref: '#/components/schemas/paypal_wallet_stored_credential' experience_status: type: string 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. readOnly: true minLength: 1 maxLength: 255 pattern: ^[A-Z_]+$ x-enumDescriptions: - value: NOT_STARTED description: PayPal checkout process has not yet begun. - value: IN_PROGRESS description: >- PayPal checkout initiated. User is on the checkout page for order review before approval. - value: CANCELED description: >- PayPal checkout is canceled (by closing the checkout window or clicking cancel) before the order approval. - value: APPROVED description: Order is approved. User has completed the checkout process. enum: - NOT_STARTED - IN_PROGRESS - CANCELED - APPROVED apple_pay: type: object title: ApplePay payment response object description: Information needed to pay using ApplePay. 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: $ref: '#/components/schemas/full_name' description: Name on the wallet. email_address: $ref: '#/components/schemas/email_address' description: >- The email address of the account holder associated with this payment method. 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 title: Phone properties: national_number: type: string 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). minLength: 1 maxLength: 14 pattern: ^[0-9]{1,14}?$ required: - national_number card: $ref: '#/components/schemas/apple_pay_card_response' description: The payment card information. attributes: $ref: '#/components/schemas/apple_pay_attributes_response' description: Additional attributes associated with apple pay. stored_credential: $ref: '#/components/schemas/card_stored_credential' google_pay: type: object title: Google Pay Wallet Response description: Google Pay Wallet payment data. properties: name: $ref: '#/components/schemas/full_name' description: Name on the account holder associated with Google Pay. email_address: $ref: '#/components/schemas/email_address' description: The email address of the account holder associated with Google Pay. 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 title: Phone properties: country_code: type: string 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). minLength: 1 maxLength: 3 pattern: ^[0-9]{1,3}?$ national_number: type: string 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). minLength: 1 maxLength: 14 pattern: ^[0-9]{1,14}?$ required: - country_code - national_number card: $ref: '#/components/schemas/google_pay_card_response' description: The Card from Google Pay Wallet used to fund the payment. venmo_wallet_response: type: object title: Venmo Wallet Response description: Venmo wallet response. properties: email_address: $ref: '#/components/schemas/email' description: The email address of the payer. account_id: $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 pattern: ^[-a-zA-Z0-9_]*$ minLength: 1 maxLength: 50 name: description: The name of the party. type: object title: Name properties: given_name: type: string description: When the party is a person, the party's given, or first, name. maxLength: 140 surname: type: string 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. maxLength: 140 phone_number: $ref: '#/components/schemas/phone' 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: 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 title: Portable Postal Address (Medium-Grained) properties: address_line_1: type: string 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. maxLength: 300 address_line_2: type: string description: >- The second line of the address, for example, a suite or apartment number. maxLength: 300 admin_area_2: type: string description: A city, town, or village. Smaller than `admin_area_level_1`. maxLength: 120 admin_area_1: type: string 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: maxLength: 300 postal_code: type: string 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). maxLength: 60 country_code: $ref: '#/components/schemas/country_code' required: - country_code attributes: $ref: '#/components/schemas/venmo_wallet_attributes_response' crypto: {} checkout_payment_intent: type: string title: Checkout Payment Intent description: >- The intent to either capture payment immediately or authorize a payment for an order after order creation. x-enumDescriptions: - value: CAPTURE description: >- The merchant intends to capture payment immediately after the customer makes a payment. - value: AUTHORIZE description: >- The merchant intends to authorize a payment and place funds on hold after the customer makes a payment. Authorized payments are best captured within three days of authorization but are available to capture for up to 29 days. After the three-day honor period, the original authorized payment expires and you must re-authorize the payment. You must make a separate request to capture payments on demand. This intent is not supported when you have more than one `purchase_unit` within your order. enum: - CAPTURE - AUTHORIZE processing_instruction: {} payer: allOf: - $ref: '#/components/schemas/payer_base' - properties: name: description: The name of the party. type: object title: Name properties: given_name: type: string description: >- When the party is a person, the party's given, or first, name. maxLength: 140 surname: type: string 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. maxLength: 140 phone: $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: $ref: '#/components/schemas/date_no_time' description: The birth date of the payer in `YYYY-MM-DD` format. tax_info: $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: 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 title: Portable Postal Address (Medium-Grained) properties: address_line_1: type: string 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. maxLength: 300 address_line_2: type: string description: >- The second line of the address, for example, a suite or apartment number. maxLength: 300 admin_area_2: type: string description: A city, town, or village. Smaller than `admin_area_level_1`. maxLength: 120 admin_area_1: type: string 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: maxLength: 300 postal_code: type: string 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). maxLength: 60 country_code: $ref: '#/components/schemas/country_code' required: - country_code - type: object title: Payer description: >- The customer who approves and pays for the order. The customer is also known as the payer. format: payer_v1 purchase_unit_list: type: array 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. minItems: 1 maxItems: 10 items: $ref: '#/components/schemas/purchase_unit' order_status: type: string description: The order status. title: Order Status minLength: 1 maxLength: 255 pattern: ^[0-9A-Z_]+$ x-enumDescriptions: - value: CREATED description: The order was created with the specified context. - value: SAVED description: >- The order was saved and persisted. The order status continues to be in progress until a capture is made with final_capture = true for all purchase units within the order. - value: APPROVED description: >- The customer approved the payment through the PayPal wallet or another form of guest or unbranded payment. For example, a card, bank account, or so on. - value: VOIDED description: All purchase units in the order are voided. - value: COMPLETED description: >- The intent of the order was completed and a `payments` resource was created. Important: Check the payment status in `purchase_units[].payments.captures[].status` before fulfilling the order. A completed order can indicate a payment was authorized, an authorized payment was captured, or a payment was declined. - value: PAYER_ACTION_REQUIRED description: >- The order requires an action from the payer (e.g. 3DS authentication). Redirect the payer to the "rel":"payer-action" HATEOAS link returned as part of the response prior to authorizing or capturing the order. Some payment sources may not return a payer-action HATEOAS link (eg. MB WAY). For these payment sources the payer-action is managed by the scheme itself (eg. through SMS, email, in-app notification, etc). enum: - CREATED - SAVED - APPROVED - VOIDED - COMPLETED - PAYER_ACTION_REQUIRED link_description_list: type: array description: An array of request-related HATEOAS links. readOnly: true minItems: 1 maxItems: 10 items: $ref: '#/components/schemas/link_description' error_details: title: Error Details type: object description: The error details. Required for client-side `4XX` errors. properties: field: type: string 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. value: type: string description: The value of the field that caused the error. location: $ref: '#/components/schemas/error_location' issue: type: string description: The unique, fine-grained application-level error code. description: type: string 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. required: - issue error_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: 20000 pattern: ^.*$ 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: 100 pattern: ^.*$ method: description: The HTTP method required to make the related call. type: string minLength: 3 maxLength: 6 pattern: ^[A-Z]*$ enum: - GET - POST - PUT - DELETE - PATCH error_default: description: The default error response. oneOf: - $ref: '#/components/schemas/error_400' - $ref: '#/components/schemas/error_401' - $ref: '#/components/schemas/error_403' - $ref: '#/components/schemas/error_404' - $ref: '#/components/schemas/error_409' - $ref: '#/components/schemas/error_415' - $ref: '#/components/schemas/error_422' - $ref: '#/components/schemas/error_429' - $ref: '#/components/schemas/error_500' - $ref: '#/components/schemas/error_503' date_year_month: type: string 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). minLength: 7 maxLength: 7 pattern: ^[0-9]{4}-(0[1-9]|1[0-2])$ country_code: type: string 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.
format: ppaas_common_country_code_v2 maxLength: 2 minLength: 2 pattern: ^([A-Z]{2}|C2)$ card_attributes: type: object title: Card Attributes description: Additional attributes associated with the use of this card. properties: customer: $ref: '#/components/schemas/card_customer' vault: $ref: '#/components/schemas/vault_instruction_base' description: Instruction to vault the card based on the specified strategy. verification: $ref: '#/components/schemas/card_verification' description: >- Instruction to optionally verify the card based on the specified strategy. vault_id: type: string 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. minLength: 1 maxLength: 255 pattern: ^[0-9a-zA-Z_-]+$ single_use_token: type: string description: >- The PayPal-generated, short-lived, one-time-use token, used to communicate payment information to PayPal for transaction processing. minLength: 1 maxLength: 255 pattern: ^[0-9a-zA-Z_-]+$ card_stored_credential: type: object 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:
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' required: - payment_initiator - payment_type network_token_request: type: object title: Network Token description: The Third Party Network token used to fund a payment. properties: number: type: string description: Third party network token number. pattern: ^[0-9]{13,19}$ minLength: 13 maxLength: 19 expiry: $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: type: string 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. pattern: ^.*$ minLength: 28 maxLength: 32 eci_flag: $ref: '#/components/schemas/eci_flag' token_requestor_id: type: string 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. pattern: ^[0-9A-Z_]+$ minLength: 1 maxLength: 11 required: - number - expiry card_experience_context: type: object title: Card Experience Context description: Customizes the payer experience during the 3DS Approval for payment. properties: return_url: $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: $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: type: string 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.
format: merchant_common_email_address_v2 maxLength: 254 minLength: 3 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])+)\]) phone_with_type: type: object title: Phone With Type description: The phone information. properties: phone_type: $ref: '#/components/schemas/phone_type' 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 title: Phone properties: national_number: type: string 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). minLength: 1 maxLength: 14 pattern: ^[0-9]{1,14}?$ required: - national_number required: - phone_number date_no_time: type: string 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. format: ppaas_date_notime_v2 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: type: object description: >- The tax ID of the customer. The customer is also known as the payer. Both `tax_id` and `tax_id_type` are required. title: Tax Info properties: tax_id: type: string description: The customer's tax ID value. minLength: 1 maxLength: 14 pattern: ([a-zA-Z0-9]) tax_id_type: type: string description: The customer's tax ID type. minLength: 1 maxLength: 14 pattern: ^[A-Z0-9_]+$ x-enumDescriptions: - value: BR_CPF description: The individual tax ID type, typically is 11 characters long. - value: BR_CNPJ description: The business tax ID type, typically is 14 characters long. enum: - BR_CPF - BR_CNPJ required: - tax_id - tax_id_type paypal_wallet_attributes: type: object title: PayPal Wallet Attributes description: Additional attributes associated with the use of this PayPal Wallet. properties: customer: $ref: '#/components/schemas/paypal_wallet_customer' vault: allOf: - $ref: '#/components/schemas/vault_instruction_base' - properties: description: type: string 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. minLength: 1 maxLength: 128 usage_pattern: title: PayPal Payment Token Usage Pattern type: string description: Expected business/pricing model for the billing agreement. minLength: 1 maxLength: 30 x-enumDescriptions: - value: IMMEDIATE description: >- On-demand instant payments – non-recurring, pre-paid, variable amount, variable frequency. - value: DEFERRED description: >- Pay after use, non-recurring post-paid, variable amount, irregular frequency. - value: RECURRING_PREPAID description: >- Pay upfront fixed or variable amount on a fixed date before the goods/service is delivered. - value: RECURRING_POSTPAID description: >- Pay on a fixed date based on usage or consumption after the goods/service is delivered. - value: THRESHOLD_PREPAID description: >- Charge payer when the set amount is reached or monthly billing cycle, whichever comes first, before the goods/service is delivered. - value: THRESHOLD_POSTPAID description: >- Charge payer when the set amount is reached or monthly billing cycle, whichever comes first, after the goods/service is delivered. - value: SUBSCRIPTION_PREPAID description: >- Subscription plan where the "amount due" and the "billing frequency" are fixed, and there is no defined duration with the payment due before the good/service is delivered. - value: SUBSCRIPTION_POSTPAID description: >- Subscription plan where the "amount due" and the "billing frequency" are fixed, and there is no defined duration with the payment due after the goods/services are delivered. - value: UNSCHEDULED_PREPAID description: >- Unscheduled card on file plan where the merchant can bill buyer upfront based on an agreed logic, but "amount due" and "frequency" can vary. Inclusive of automatic reload plans. - value: UNSCHEDULED_POSTPAID description: >- Unscheduled card on file plan where the merchant can bill buyer based on an agreed logic, but "amount due" and "frequency" can vary. Inclusive of automatic reload plans. - value: INSTALLMENT_PREPAID description: >- Merchant-managed installment plan when the "amount" to be paid and the "billing frequency" are fixed, but there is a defined number of payments with the payment due before the good/service is delivered. - value: INSTALLMENT_POSTPAID description: >- Merchant-managed installment plan when the "amount" to be paid and the "billing frequency" are fixed, but there is a defined number of payments with the payment due after the goods/services are delivered. enum: - IMMEDIATE - DEFERRED - RECURRING_PREPAID - RECURRING_POSTPAID - THRESHOLD_PREPAID - THRESHOLD_POSTPAID - SUBSCRIPTION_PREPAID - SUBSCRIPTION_POSTPAID - UNSCHEDULED_PREPAID - UNSCHEDULED_POSTPAID - INSTALLMENT_PREPAID - INSTALLMENT_POSTPAID usage_type: title: PayPal Payment Token Usage Type type: string description: The usage type associated with the PayPal payment token. minLength: 1 maxLength: 255 pattern: ^[0-9A-Z_]+$ x-enumDescriptions: - value: MERCHANT description: >- The PayPal Payment Token will be used for future transaction directly with a merchant. - value: PLATFORM description: >- The PayPal Payment Token will be used for future transaction on a platform. A platform is typically a marketplace or a channel that a payer can purchase goods and services from multiple merchants. enum: - MERCHANT - PLATFORM customer_type: title: PayPal Payment Token Customer Type type: string 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. minLength: 1 maxLength: 255 pattern: ^[0-9A-Z_]+$ default: CONSUMER x-enumDescriptions: - value: CONSUMER description: >- The customer vaulting the PayPal payment token is a consumer on the merchant / platform. - value: BUSINESS description: >- The customer vaulting the PayPal payment token is a business on merchant / platform. enum: - CONSUMER - BUSINESS permit_multiple_payment_tokens: type: boolean 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. default: false - type: object title: Vaulted PayPal Wallet Common Attributes description: >- Resource consolidating common request and response attributes for vaulting PayPal Wallet. required: - usage_type - description: >- Attributes used to provide the instructions during vaulting of the PayPal Wallet. paypal_wallet_experience_context: type: object 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.
properties: brand_name: type: string 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. minLength: 1 maxLength: 127 pattern: ^.*$ locale: $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: type: string description: The location from which the shipping address is derived. minLength: 1 maxLength: 24 pattern: ^[A-Z_]+$ default: GET_FROM_FILE x-enumDescriptions: - value: GET_FROM_FILE description: Get the customer-provided shipping address on the PayPal site. - value: NO_SHIPPING description: >- Removes the shipping address information from the API response and the Paypal site. However, the shipping.phone_number and shipping.email_address fields will still be returned to allow for digital goods delivery. - value: SET_PROVIDED_ADDRESS description: >- Get the merchant-provided address. The customer cannot change this address on the PayPal site. If merchant does not pass an address, customer can choose the address on PayPal pages. enum: - GET_FROM_FILE - NO_SHIPPING - SET_PROVIDED_ADDRESS contact_preference: type: string description: >- The preference to display the contact information (buyer’s shipping email & phone number) on PayPal's checkout for easy merchant-buyer communication. minLength: 1 maxLength: 24 pattern: ^[A-Z_]+$ default: NO_CONTACT_INFO x-enumDescriptions: - value: NO_CONTACT_INFO description: >- The merchant can opt out of showing buyer's contact information on PayPal checkout. - value: UPDATE_CONTACT_INFO description: >- The merchant allows buyer to add or update shipping contact information on the PayPal checkout. Please ensure to use this updated information returned in shipping.email_address and shipping.phone_number to contact your buyers. - value: RETAIN_CONTACT_INFO description: >- The buyer can only see but can not override merchant passed contact information (shipping.email_address and shipping.phone_number) on PayPal checkout. NOTE: If you don't pass the contact information, the behavior is the same as NO_CONTACT_INFO preference. enum: - NO_CONTACT_INFO - UPDATE_CONTACT_INFO - RETAIN_CONTACT_INFO return_url: $ref: '#/components/schemas/url' description: >- The URL where the customer will be redirected upon approving a payment. format: uri cancel_url: $ref: '#/components/schemas/url' description: >- The URL where the customer will be redirected upon cancelling the payment approval. format: uri app_switch_context: $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: type: string description: >- The type of landing page to show on the PayPal site for customer checkout. default: NO_PREFERENCE x-enumDescriptions: - value: LOGIN description: >- When the customer clicks PayPal Checkout, the customer is redirected to a page to log in to PayPal and approve the payment. - value: GUEST_CHECKOUT description: >- When the customer clicks PayPal Checkout, the customer is redirected to a page to enter credit or debit card and other relevant billing information required to complete the purchase. This option has previously been also called as 'BILLING' - value: NO_PREFERENCE description: >- When the customer clicks PayPal Checkout, the customer is redirected to either a page to log in to PayPal and approve the payment or to a page to enter credit or debit card and other relevant billing information required to complete the purchase, depending on their previous interaction with PayPal. minLength: 1 maxLength: 13 pattern: ^[0-9A-Z_]+$ enum: - LOGIN - GUEST_CHECKOUT - NO_PREFERENCE user_action: type: string description: >- Configures a Continue or Pay Now checkout flow. default: CONTINUE x-enumDescriptions: - value: CONTINUE description: >- After you redirect the customer to the PayPal payment page, a Continue button appears. Use this option when the final amount is not known when the checkout flow is initiated and you want to redirect the customer to the merchant page without processing the payment. default: true - value: PAY_NOW description: >- After you redirect the customer to the PayPal payment page, a Pay Now button appears. Use this option when the final amount is known when the checkout is initiated and you want to process the payment immediately when the customer clicks Pay Now. minLength: 1 maxLength: 8 pattern: ^[0-9A-Z_]+$ enum: - CONTINUE - PAY_NOW payment_method_preference: type: string description: The merchant-preferred payment methods. minLength: 1 maxLength: 255 pattern: ^[0-9A-Z_]+$ default: UNRESTRICTED x-enumDescriptions: - value: UNRESTRICTED description: Accepts any type of payment from the customer. default: true - value: IMMEDIATE_PAYMENT_REQUIRED description: >- Accepts only immediate payment from the customer. For example, credit card, PayPal balance, or instant ACH. Ensures that at the time of capture, the payment does not have the `pending` status. enum: - UNRESTRICTED - IMMEDIATE_PAYMENT_REQUIRED order_update_callback_config: $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: type: string description: >- The PayPal billing agreement ID. References an approved recurring payment for goods or services. minLength: 2 maxLength: 128 pattern: ^[a-zA-Z0-9-]+$ paypal_wallet_stored_credential: type: object title: PayPal Wallet stored credentials 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. properties: payment_initiator: $ref: '#/components/schemas/payment_initiator' charge_pattern: $ref: '#/components/schemas/charge_pattern' description: >- DEPRECATED. Expected business/pricing model for the billing agreement, Please use usage_pattern instead. deprecated: true usage_pattern: $ref: '#/components/schemas/charge_pattern' usage: $ref: '#/components/schemas/stored_payment_source_usage_type' required: - payment_initiator full_name: type: string description: The full name representation like Mr J Smith. minLength: 3 maxLength: 300 email_address: type: string 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.
format: ppaas_common_email_address_v2 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])+)\])$ apple_pay_decrypted_token_data: type: object title: ApplePay Decrypted Token Data description: >- Information about the Payment data obtained by decrypting Apple Pay token. properties: transaction_amount: $ref: '#/components/schemas/money' description: >- The transaction amount for the payment that the payer has approved on apple platform. tokenized_card: description: >- The payment card to use to fund a payment. Can be a credit or debit card. type: object title: Card properties: name: type: string description: The card holder's name as it appears on the card. maxLength: 300 minLength: 1 pattern: ^.{1,300}$ number: type: string description: The primary account number (PAN) for the payment card. pattern: ^[0-9]{13,19}$ minLength: 13 maxLength: 19 expiry: $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 card_type: $ref: '#/components/schemas/card_brand' description: The card brand or network. Typically used in the response. readOnly: true deprecated: true type: $ref: '#/components/schemas/card_type' description: The payment card type. brand: $ref: '#/components/schemas/card_brand' description: The card brand or network. Typically used in the response. billing_address: 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 title: Portable Postal Address (Medium-Grained) properties: address_line_1: type: string 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. maxLength: 300 address_line_2: type: string description: >- The second line of the address, for example, a suite or apartment number. maxLength: 300 admin_area_2: type: string description: A city, town, or village. Smaller than `admin_area_level_1`. maxLength: 120 admin_area_1: type: string 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: maxLength: 300 postal_code: type: string 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). maxLength: 60 country_code: $ref: '#/components/schemas/country_code' required: - country_code 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 minLength: 1 maxLength: 16 pattern: ^[0-9A-Z_]+$ x-enumDescriptions: - value: 3DSECURE description: >- The card was authenticated using 3D Secure (3DS) authentication scheme. While using this value make sure to populate cryptogram and eci_indicator as part of payment data.. - value: EMV description: >- The card was authenticated using EMV method, which is applicable for China. While using this value make sure to pass emv_data and pin as part of payment data. enum: - 3DSECURE - EMV payment_data: $ref: '#/components/schemas/apple_pay_payment_data' description: >- Apple Pay payment data object which contains the cryptogram, eci_indicator and other data. required: - tokenized_card apple_pay_attributes: type: object title: Apple Pay Attributes description: Additional attributes associated with apple pay. properties: customer: $ref: '#/components/schemas/customer' vault: $ref: '#/components/schemas/v3_vault_instruction_base' apple_pay_experience_context: type: object title: Apple Pay Experience Context description: >- Customizes the payer experience during the approval process for the payment. properties: return_url: $ref: '#/components/schemas/url' description: >- The URL where the customer is redirected after the customer approves the payment. format: uri cancel_url: $ref: '#/components/schemas/url' description: >- The URL where the customer is redirected after the customer cancels the payment. format: uri required: - return_url - cancel_url card_type: type: string title: Card Type description: Type of card. i.e Credit, Debit and so on. minLength: 1 maxLength: 255 pattern: ^[A-Z_]+$ x-enumDescriptions: - value: CREDIT description: A credit card. - value: DEBIT description: A debit card. - value: PREPAID description: A Prepaid card. - value: STORE description: A store card. - value: UNKNOWN description: Card type cannot be determined. enum: - CREDIT - DEBIT - PREPAID - STORE - UNKNOWN card_brand: type: string title: Card Brand description: >- The card network or brand. Applies to credit, debit, gift, and payment cards. minLength: 1 maxLength: 255 pattern: ^[A-Z_]+$ x-enumDescriptions: - value: VISA description: Visa card. - value: MASTERCARD description: Mastercard card. - value: DISCOVER description: Discover card. - value: AMEX description: American Express card. - value: SOLO description: Solo debit card. - value: JCB description: Japan Credit Bureau card. - value: STAR description: Military Star card. - value: DELTA description: Delta Airlines card. - value: SWITCH description: Switch credit card. - value: MAESTRO description: Maestro credit card. - value: CB_NATIONALE description: Carte Bancaire (CB) credit card. - value: CONFIGOGA description: Configoga credit card. - value: CONFIDIS description: Confidis credit card. - value: ELECTRON description: Visa Electron credit card. - value: CETELEM description: Cetelem credit card. - value: CHINA_UNION_PAY description: China union pay credit card. - value: DINERS description: >- The Diners Club International banking and payment services capability network owned by Discover Financial Services (DFS), one of the most recognized brands in US financial services. - value: ELO description: The Brazilian Elo card payment network. - value: HIPER description: The Hiper - Ingenico ePayment network. - value: HIPERCARD description: >- The Brazilian Hipercard payment network that's widely accepted in the retail market. - value: RUPAY description: The RuPay payment network. - value: GE description: The GE Credit Union 3Point card payment network. - value: SYNCHRONY description: The Synchrony Financial (SYF) payment network. - value: EFTPOS description: >- The Electronic Fund Transfer At Point of Sale(EFTPOS) Debit card payment network. - value: CARTE_BANCAIRE description: The Carte Bancaire payment network. - value: STAR_ACCESS description: The Star Access payment network. - value: PULSE description: The Pulse payment network. - value: NYCE description: The NYCE payment network. - value: ACCEL description: The Accel payment network. - value: UNKNOWN description: UNKNOWN payment network. 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 google_pay_decrypted_token_data: type: object title: Google Pay payment request object 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. 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 pattern: \d{13} minLength: 13 maxLength: 13 payment_method: description: >- The type of the payment credential. Currently, only CARD is supported. type: string minLength: 4 maxLength: 4 x-enumDescriptions: - value: CARD description: CARD is the only value that Google Pay accepts. enum: - CARD card: description: >- The payment card used to fund a Google Pay payment. Can be a credit or debit card. type: object title: Google Pay Card properties: name: type: string description: The card holder's name as it appears on the card. maxLength: 300 minLength: 1 pattern: ^.{1,300}$ number: type: string description: The primary account number (PAN) for the payment card. pattern: ^[0-9]{13,19}$ minLength: 13 maxLength: 19 expiry: $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: type: string description: The last digits of the payment card. pattern: ^[0-9]{2,4}$ minLength: 2 maxLength: 4 readOnly: true type: $ref: '#/components/schemas/card_type' description: The payment card type. brand: $ref: '#/components/schemas/card_brand' description: The card brand or network. Typically used in the response. billing_address: 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 title: Portable Postal Address (Medium-Grained) properties: address_line_1: type: string 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. maxLength: 300 address_line_2: type: string description: >- The second line of the address, for example, a suite or apartment number. maxLength: 300 admin_area_2: type: string description: A city, town, or village. Smaller than `admin_area_level_1`. maxLength: 120 admin_area_1: type: string 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: maxLength: 300 postal_code: type: string 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). maxLength: 60 country_code: $ref: '#/components/schemas/country_code' required: - country_code authentication_method: description: Authentication Method which is used for the card transaction. type: string minLength: 1 maxLength: 50 x-enumDescriptions: - value: PAN_ONLY description: >- This authentication method is associated with payment cards stored on file with the user's Google Account. Returned payment data includes primary account number (PAN) with the expiration month and the expiration year. - value: CRYPTOGRAM_3DS description: >- Returned payment data includes a 3-D Secure (3DS) cryptogram generated on the device. -> If authentication_method=CRYPTOGRAM, it is required that 'cryptogram' parameter in the request has a valid 3-D Secure (3DS) cryptogram generated on the device. 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 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: ^.*$ required: - payment_method - card - authentication_method assurance_details: type: object title: Assurance Details description: >- Information about cardholder possession validation and cardholder identification and verifications (ID&V). 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_attributes: {} google_pay_experience_context: type: object title: Google Pay Experience Context description: >- Customizes the payer experience during the approval process for the payment. properties: return_url: $ref: '#/components/schemas/url' description: >- The URL where the customer is redirected after the customer approves the payment. format: uri cancel_url: $ref: '#/components/schemas/url' description: >- The URL where the customer is redirected after the customer cancels the payment. format: uri required: - return_url - cancel_url venmo_wallet_experience_context: type: object 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.
properties: brand_name: type: string description: >- The business name of the merchant. The pattern is defined by an external party and supports Unicode. minLength: 1 maxLength: 127 pattern: ^.*$ shipping_preference: type: string description: The location from which the shipping address is derived. minLength: 1 maxLength: 24 pattern: ^[A-Z_]+$ default: GET_FROM_FILE x-enumDescriptions: - value: GET_FROM_FILE description: Get the customer-provided shipping address on the PayPal site. - value: NO_SHIPPING description: >- Redacts the shipping address from the PayPal site. Recommended for digital goods. - value: SET_PROVIDED_ADDRESS description: >- Get the merchant-provided address. The customer cannot change this address on the PayPal site. If merchant does not pass an address, customer can choose the address on PayPal pages. enum: - GET_FROM_FILE - NO_SHIPPING - SET_PROVIDED_ADDRESS order_update_callback_config: $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'. venmo_wallet_attributes: type: object title: Venmo Wallet Attributes description: Additional attributes associated with the use of this Venmo Wallet. properties: customer: $ref: '#/components/schemas/customer' vault: $ref: '#/components/schemas/vault_venmo_wallet_base' description: >- Attributes used to provide the instructions during vaulting of the Venmo Wallet. date_time: type: string 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.
format: ppaas_date_time_v3 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_brand_list: type: array description: Array of brands or networks associated with the card. readOnly: true minItems: 1 maxItems: 256 items: $ref: '#/components/schemas/card_brand' authentication_response: type: object title: Authentication Response description: Results of Authentication such as 3D Secure. properties: liability_shift: $ref: '#/components/schemas/liability_shift' three_d_secure: $ref: '#/components/schemas/three_d_secure_authentication_response' card_attributes_response: type: object title: Card Attributes Response description: Additional attributes associated with the use of this card. properties: vault: $ref: '#/components/schemas/card_vault_response' card_from_request: type: object title: Card from Request description: Representation of card details as received in the request. properties: expiry: $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: type: string description: The last digits of the payment card. pattern: '[0-9]{2,}' minLength: 2 maxLength: 4 readOnly: true bin_details: type: object title: Bin Details description: Bank Identification Number (BIN) details used to fund a payment. properties: bin: type: string 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. pattern: ^[0-9]+$ maxLength: 25 minLength: 1 issuing_bank: type: string description: The issuer of the card instrument. minLength: 1 maxLength: 64 bin_country_code: $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: $ref: '#/components/schemas/products_list' account_id-2: type: string 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. format: ppaas_payer_id_v3 minLength: 13 maxLength: 13 pattern: ^[2-9A-HJ-NP-Z]{13}$ phone_type: type: string title: Phone Type description: The phone type. enum: - FAX - HOME - MOBILE - OTHER - PAGER x-enumDescriptions: - value: FAX description: Fax number. - value: HOME description: Home phone number. - value: MOBILE description: Mobile phone number. - value: OTHER description: Other phone number. - value: PAGER description: Pager number. phone: type: object 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). properties: national_number: type: string 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). minLength: 1 maxLength: 14 pattern: ^[0-9]{1,14}?$ required: - national_number paypal_wallet_attributes_response: type: object title: PayPal Wallet Attributes Response description: Additional attributes associated with the use of a PayPal Wallet. properties: vault: $ref: '#/components/schemas/paypal_wallet_vault_response' cobranded_cards: $ref: '#/components/schemas/cobranded_card_list' apple_pay_card_response: type: object title: Apple Pay Card Response description: The Card from Apple Pay Wallet used to fund the payment. properties: name: type: string description: The card holder's name as it appears on the card. minLength: 2 maxLength: 300 last_digits: type: string description: The last digits of the payment card. pattern: '[0-9]{2,}' readOnly: true brand: $ref: '#/components/schemas/card_brand' description: The card brand or network. Typically used in the response. readOnly: true available_networks: $ref: '#/components/schemas/card_brand_list' type: $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: $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: $ref: '#/components/schemas/bin_details' description: Bank Identification Number (BIN) details used to fund a payment. stored_credential: $ref: '#/components/schemas/card_stored_credential' billing_address: 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 title: Portable Postal Address (Medium-Grained) properties: address_line_1: type: string 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. maxLength: 300 address_line_2: type: string description: >- The second line of the address, for example, a suite or apartment number. maxLength: 300 admin_area_2: type: string description: A city, town, or village. Smaller than `admin_area_level_1`. maxLength: 120 admin_area_1: type: string 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: maxLength: 300 postal_code: type: string 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). maxLength: 60 country_code: $ref: '#/components/schemas/country_code' required: - country_code country_code: $ref: '#/components/schemas/country_code-2' description: The country where the card is issued. apple_pay_attributes_response: type: object title: Apple Pay Attributes Response description: Additional attributes associated with the use of Apple Pay. properties: vault: $ref: '#/components/schemas/vault_response' google_pay_card_response: type: object 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. properties: name: type: string description: The card holder's name as it appears on the card. maxLength: 300 minLength: 1 pattern: ^.{1,300}$ last_digits: type: string description: The last digits of the payment card. pattern: ^[0-9]{2,4}$ minLength: 2 maxLength: 4 readOnly: true type: $ref: '#/components/schemas/card_type' description: The payment card type. brand: $ref: '#/components/schemas/card_brand' description: The card brand or network. Typically used in the response. billing_address: 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 title: Portable Postal Address (Medium-Grained) properties: address_line_1: type: string 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. maxLength: 300 address_line_2: type: string description: >- The second line of the address, for example, a suite or apartment number. maxLength: 300 admin_area_2: type: string description: A city, town, or village. Smaller than `admin_area_level_1`. maxLength: 120 admin_area_1: type: string 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: maxLength: 300 postal_code: type: string 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). maxLength: 60 country_code: $ref: '#/components/schemas/country_code' required: - country_code authentication_result: $ref: '#/components/schemas/authentication_response' venmo_wallet_attributes_response: type: object title: Venmo Wallet Attributes Response description: Additional attributes associated with the use of a Venmo Wallet. properties: vault: $ref: '#/components/schemas/vault_response' payer_base: type: object title: Payer Base description: >- The customer who approves and pays for the order. The customer is also known as the payer. properties: email_address: $ref: '#/components/schemas/email' description: The email address of the payer. payer_id: $ref: '#/components/schemas/account_id' description: The PayPal-assigned ID for the payer. readOnly: true purchase_unit: type: object title: Purchase Unit description: >- The purchase unit details. Used to capture required information for the payment contract. properties: reference_id: type: string 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.
minLength: 1 maxLength: 256 amount: $ref: '#/components/schemas/amount_with_breakdown' payee: $ref: '#/components/schemas/payee' description: The merchant who receives payment for this transaction. payment_instruction: $ref: '#/components/schemas/payment_instruction' description: type: string description: The purchase description. minLength: 1 maxLength: 127 custom_id: type: string description: >- The API caller-provided external ID. Used to reconcile API caller-initiated transactions with PayPal transactions. Appears in transaction and settlement reports. minLength: 1 maxLength: 255 invoice_id: type: string description: The API caller-provided external invoice ID for this order. minLength: 1 maxLength: 127 id: type: string 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. minLength: 1 maxLength: 19 soft_descriptor: type: string 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:For Wallet payments marketplace integrations:
For unbranded payments (Direct Card) marketplace integrations, use a combination of the seller name and phone number. minLength: 1 maxLength: 22 items: $ref: '#/components/schemas/item_list' shipping: $ref: '#/components/schemas/shipping_with_tracking_details' description: The shipping address and method. supplementary_data: $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: $ref: '#/components/schemas/payment_collection' description: The comprehensive history of payments for the purchase unit. readOnly: true most_recent_errors: $ref: '#/components/schemas/most_recent_error_list' link_description: type: object title: Link Description description: >- The request-related [HATEOAS link](/api/rest/responses/#hateoas-links) information. required: - href - rel properties: href: type: string 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. rel: type: string 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). method: type: string description: The HTTP method required to make the related call. enum: - GET - POST - PUT - DELETE - HEAD - CONNECT - OPTIONS - PATCH x-enumDescriptions: - value: GET description: The HTTP GET method. - value: POST description: The HTTP POST method. - value: PUT description: The HTTP PUT method. - value: DELETE description: The HTTP DELETE method. - value: HEAD description: The HTTP HEAD method. - value: CONNECT description: The HTTP CONNECT method. - value: OPTIONS description: The HTTP OPTIONS method. - value: PATCH description: The HTTP PATCH method. error_location: type: string description: >- The location of the field that caused the error. Value is `body`, `path`, or `query`. enum: - body - path - query default: body error_409: type: object title: Resource Conflict Error description: The server has detected a conflict while processing this request. properties: name: type: string enum: - RESOURCE_CONFLICT message: type: string enum: - The server has detected a conflict while processing this request. details: type: array items: $ref: '#/components/schemas/error_details' debug_id: type: string description: The PayPal internal ID. Used for correlation purposes. links: description: >- An array of request-related [HATEOAS links](https://en.wikipedia.org/wiki/HATEOAS). type: array minItems: 0 maxItems: 10000 items: $ref: '#/components/schemas/error_link_description' error_415: type: object title: Unsupported Media Type Error description: The server does not support the request payload's media type. properties: name: type: string enum: - UNSUPPORTED_MEDIA_TYPE message: type: string enum: - The server does not support the request payload's media type. details: type: array items: $ref: '#/components/schemas/error_details' debug_id: type: string description: The PayPal internal ID. Used for correlation purposes. links: description: >- An array of request-related [HATEOAS links](https://en.wikipedia.org/wiki/HATEOAS). type: array minItems: 0 maxItems: 10000 items: $ref: '#/components/schemas/error_link_description' error_429: type: object title: Too many requests description: Too many requests. Blocked due to rate limiting. properties: name: type: string enum: - RATE_LIMIT_REACHED message: type: string enum: - Too many requests. Blocked due to rate limiting. debug_id: type: string description: The PayPal internal ID. Used for correlation purposes. error_503: type: object title: Service Unavailable Error description: >- The server is temporarily unable to handle the request, for example, because of planned maintenance or downtime. properties: name: type: string enum: - SERVICE_UNAVAILABLE message: type: string enum: - Service Unavailable. debug_id: type: string description: The PayPal internal ID. Used for correlation purposes. links: description: >- An array of request-related [HATEOAS links](https://en.wikipedia.org/wiki/HATEOAS). type: array minItems: 0 maxItems: 10000 items: $ref: '#/components/schemas/error_link_description' example: name: SERVICE_UNAVAILABLE message: Service Unavailable. debug_id: 90957fca61718 information_link: >- https://developer.paypal.com/docs/api/orders/v2/#error-SERVICE_UNAVAILABLE card_customer: type: object title: Card Customer Information description: The details about a customer in PayPal's system of record. allOf: - $ref: '#/components/schemas/customer' - 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: type: object title: Vault Instruction Base description: >- Basic vault instruction specification that can be extended by specific payment sources that supports vaulting. properties: store_in_vault: $ref: '#/components/schemas/store_in_vault_instruction' card_verification: type: object 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). properties: method: description: The method used for card verification. type: string minLength: 1 maxLength: 255 pattern: ^[0-9A-Z_]+$ default: SCA_WHEN_REQUIRED x-enumDescriptions: - value: SCA_ALWAYS description: >- Selecting this option will attempt to force a strong customer authentication for the authorization/transaction. In countries where SCA has been defined and implemented it will result in a contingency and HATEOAS link being returned. The API caller should redirect the payer to that link so that they can authenticate themselves against their issuing bank or other entity. As noted, the HATEOAS link is only available in all regions where strong authentication is supported, (e.g. in European countries where 3DS is live). Merchants can use this setting as an additional layer of security if they choose to. In all cases, when an authorization is requested the AVS/CVV results will be returned in the response. - value: SCA_WHEN_REQUIRED description: >- This is the default. When an authorization or transaction is attempted this option will return a contingency and HATEOAS link only when local regulations require strong customer authentication, (e.g. 3DS in countries and use cases where it is mandated). The API caller should redirect the payer to the link so that they can authenticate themselves. In all cases, when an authorization is requested the AVS/CVV results will be returned in the response. - value: 3D_SECURE description: >- The contingency surfaced as an additional security layer that helps prevent unauthorized card-not-present transactions and protects the merchant from exposure to fraud. deprecated: true - value: AVS_CVV description: >- Places a temporary hold on the card to ensure its validity. This process protects the merchant from exposure to fraud. This verification method will confirm that the address information or CVV included matches what the issuing bank has on file for the associated card, ensuring that only authorized card users are able to make purchases from you. deprecated: true enum: - SCA_ALWAYS - SCA_WHEN_REQUIRED - 3D_SECURE - AVS_CVV payment_initiator: type: string minLength: 1 maxLength: 255 pattern: ^[0-9A-Z_]+$ description: The person or party who initiated or triggered the payment. x-enumDescriptions: - value: CUSTOMER description: >- Payment is initiated with the active engagement of the customer. e.g. a customer checking out on a merchant website. - value: MERCHANT description: >- Payment is initiated by merchant on behalf of the customer without the active engagement of customer. e.g. a merchant charging the monthly payment of a subscription to the customer. enum: - CUSTOMER - MERCHANT stored_payment_source_payment_type: type: string minLength: 1 maxLength: 255 pattern: ^[0-9A-Z_]+$ description: Indicates the type of the stored payment_source payment. x-enumDescriptions: - value: ONE_TIME description: >- One Time payment such as online purchase or donation. (e.g. Checkout with one-click). - value: RECURRING description: >- Payment which is part of a series of payments with fixed or variable amounts, following a fixed time interval. (e.g. Subscription payments). - value: UNSCHEDULED description: >- Payment which is part of a series of payments that occur on a non-fixed schedule and/or have variable amounts. (e.g. Account Topup payments). enum: - ONE_TIME - RECURRING - UNSCHEDULED stored_payment_source_usage_type: type: string minLength: 1 maxLength: 255 pattern: ^[0-9A-Z_]+$ default: DERIVED 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). x-enumDescriptions: - value: FIRST description: >- Indicates the Initial/First payment with a payment_source that is intended to be stored upon successful processing of the payment. - value: SUBSEQUENT description: >- Indicates a payment using a stored payment_source which has been successfully used previously for a payment. - value: DERIVED description: >- Indicates that PayPal will derive the value of `FIRST` or `SUBSEQUENT` based on data available to PayPal. enum: - FIRST - SUBSEQUENT - DERIVED network_transaction_reference: type: object title: Network Transaction Reference description: Reference values used by the card network to identify a transaction. allOf: - $ref: '#/components/schemas/network_transaction' required: - id eci_flag: type: string minLength: 1 maxLength: 255 pattern: ^[0-9A-Z_]+$ 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. x-enumDescriptions: - value: MASTERCARD_NON_3D_SECURE_TRANSACTION description: Mastercard non-3-D Secure transaction. - value: MASTERCARD_ATTEMPTED_AUTHENTICATION_TRANSACTION description: Mastercard attempted authentication transaction. - value: MASTERCARD_FULLY_AUTHENTICATED_TRANSACTION description: Mastercard fully authenticated transaction. - value: FULLY_AUTHENTICATED_TRANSACTION description: VISA, AMEX, JCB, DINERS CLUB fully authenticated transaction. - value: ATTEMPTED_AUTHENTICATION_TRANSACTION description: VISA, AMEX, JCB, DINERS CLUB attempted authentication transaction. - value: NON_3D_SECURE_TRANSACTION description: VISA, AMEX, JCB, DINERS CLUB non-3-D Secure transaction. 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: type: string description: Describes the URL. format: uri paypal_wallet_customer: type: object title: PayPal Wallet Customer Information description: The details about a customer in PayPal's system of record. allOf: - $ref: '#/components/schemas/customer' - 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-_.^*$@#]+$ language: type: string 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/). format: ppaas_common_language_v3 maxLength: 10 minLength: 2 pattern: ^[a-z]{2}(?:-[A-Z][a-z]{3})?(?:-(?:[A-Z]{2}|[0-9]{3}))?$ app_switch_context: type: object 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. properties: native_app: $ref: '#/components/schemas/native_app_context' mobile_web: $ref: '#/components/schemas/mobile_web_context' callback_configuration: type: object title: CallBack Configuration that the merchant can provide to PayPal/Venmo. description: CallBack Configuration that the merchant can provide to PayPal/Venmo. properties: callback_events: $ref: '#/components/schemas/callback_events_list' callback_url: type: string 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. minLength: 10 maxLength: 2040 pattern: ^.*$ format: uri required: - callback_events - callback_url charge_pattern: type: string description: Expected business/pricing model for the billing agreement. minLength: 1 maxLength: 30 pattern: ^[A-Z0-9_]+$ x-enumDescriptions: - value: IMMEDIATE description: >- On-demand instant payments – non-recurring, pre-paid, variable amount, variable frequency. - value: DEFERRED description: >- Pay after use, non-recurring post-paid, variable amount, irregular frequency. - value: RECURRING_PREPAID description: >- Pay upfront fixed or variable amount on a fixed date before the goods/service is delivered. - value: RECURRING_POSTPAID description: >- Pay on a fixed date based on usage or consumption after the goods/service is delivered. - value: THRESHOLD_PREPAID description: >- Charge payer when the set amount is reached or monthly billing cycle, whichever comes first, before the goods/service is delivered. - value: THRESHOLD_POSTPAID description: >- Charge payer when the set amount is reached or monthly billing cycle, whichever comes first, after the goods/service is delivered. - value: SUBSCRIPTION_PREPAID description: >- Subscription plan where the "amount due" and the "billing frequency" are fixed, and there is no defined duration with the payment due before the good/service is delivered. - value: SUBSCRIPTION_POSTPAID description: >- Subscription plan where the "amount due" and the "billing frequency" are fixed, and there is no defined duration with the payment due after the goods/services are delivered. - value: UNSCHEDULED_PREPAID description: >- Unscheduled card on file plan where the merchant can bill buyer upfront based on an agreed logic, but "amount due" and "frequency" can vary. Inclusive of automatic reload plans. - value: UNSCHEDULED_POSTPAID description: >- Unscheduled card on file plan where the merchant can bill buyer based on an agreed logic, but "amount due" and "frequency" can vary. Inclusive of automatic reload plans. - value: INSTALLMENT_PREPAID description: >- Merchant-managed installment plan when the "amount" to be paid and the "billing frequency" are fixed, but there is a defined number of payments with the payment due before the good/service is delivered. - value: INSTALLMENT_POSTPAID description: >- Merchant-managed installment plan when the "amount" to be paid and the "billing frequency" are fixed, but there is a defined number of payments with the payment due after the goods/services are delivered. enum: - IMMEDIATE - DEFERRED - RECURRING_PREPAID - RECURRING_POSTPAID - THRESHOLD_PREPAID - THRESHOLD_POSTPAID - SUBSCRIPTION_PREPAID - SUBSCRIPTION_POSTPAID - UNSCHEDULED_PREPAID - UNSCHEDULED_POSTPAID - INSTALLMENT_PREPAID - INSTALLMENT_POSTPAID money: type: object title: Money description: >- The currency and amount for a financial transaction, such as a balance or payment due. properties: currency_code: $ref: '#/components/schemas/currency_code' value: type: string description: >- The value, which might be:For the required number of decimal places for a currency code, see [Currency Codes](/api/rest/reference/currency-codes/). maxLength: 32 pattern: ^((-?[0-9]+)|(-?([0-9]+)?[.][0-9]+))$ required: - currency_code - value apple_pay_payment_data: type: object title: ApplePay Payment Data description: >- Information about the decrypted apple pay payment data for the token like cryptogram, eci indicator. 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: type: object title: Customer Information description: >- This object represents a merchant’s customer, allowing them to store contact details, and track all payments associated with the same customer. properties: id: $ref: '#/components/schemas/merchant_partner_customer_id' email_address: $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: $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: description: The name of the party. type: object title: Name properties: given_name: type: string description: When the party is a person, the party's given, or first, name. maxLength: 140 surname: type: string 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. maxLength: 140 v3_vault_instruction_base: type: object title: Base Vault Instruction Parameters description: >- Base vaulting specification. The object can be extended for specific use cases within each payment_source that supports vaulting. properties: store_in_vault: $ref: '#/components/schemas/store_in_vault_instruction' required: - store_in_vault vault_venmo_wallet_base: type: object title: Vaulted Venmo Wallet Common Attributes description: >- Resource consolidating common request and response attirbutes for vaulting Venmo Wallet. allOf: - $ref: '#/components/schemas/v3_vault_instruction_base' - properties: description: type: string 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. minLength: 1 maxLength: 128 pattern: ^[a-zA-Z0-9_'\-., :;\!?"]*$ usage_pattern: title: Venmo Payment Token Usage Pattern type: string description: Expected business/pricing model for the billing agreement. minLength: 1 maxLength: 30 pattern: ^[0-9A-Z_]+$ x-enumDescriptions: - value: IMMEDIATE description: >- On-demand instant payments – non-recurring, pre-paid, variable amount, variable frequency. - value: DEFERRED description: >- Pay after use, non-recurring post-paid, variable amount, irregular frequency. - value: RECURRING_PREPAID description: >- Pay upfront fixed or variable amount on a fixed date before the goods/service is delivered. - value: RECURRING_POSTPAID description: >- Pay on a fixed date based on usage or consumption after the goods/service is delivered. - value: THRESHOLD_PREPAID description: >- Charge payer when the set amount is reached or monthly billing cycle, whichever comes first, before the goods/service is delivered. - value: THRESHOLD_POSTPAID description: >- Charge payer when the set amount is reached or monthly billing cycle, whichever comes first, after the goods/service is delivered. enum: - IMMEDIATE - DEFERRED - RECURRING_PREPAID - RECURRING_POSTPAID - THRESHOLD_PREPAID - THRESHOLD_POSTPAID usage_type: title: Venmo Payment Token Usage Type type: string description: The usage type associated with the Venmo payment token. minLength: 1 maxLength: 255 pattern: ^[0-9A-Z_]+$ x-enumDescriptions: - value: MERCHANT description: >- The Venmo Payment Token will be used for future transaction directly with a merchant. - value: PLATFORM description: >- The Venmo Payment Token will be used for future transaction on a platform. A platform is typically a marketplace or a channel that a payer can purchase goods and services from multiple merchants. enum: - MERCHANT - PLATFORM customer_type: title: Venmo Payment Token Customer Type type: string 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. minLength: 1 maxLength: 255 pattern: ^[0-9A-Z_]+$ default: CONSUMER x-enumDescriptions: - value: CONSUMER description: >- The customer vaulting the Venmo payment token is a consumer on the merchant / platform. - value: BUSINESS description: >- The customer vaulting the Venmo payment token is a business on merchant / platform. enum: - CONSUMER - BUSINESS permit_multiple_payment_tokens: type: boolean 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. default: false required: - usage_type liability_shift: type: string minLength: 1 maxLength: 255 pattern: ^[0-9A-Z_]+$ description: Liability shift indicator. The outcome of the issuer's authentication. x-enumDescriptions: - value: 'NO' description: Liability is with the merchant. - value: POSSIBLE description: Liability may shift to the card issuer. - value: UNKNOWN description: The authentication system is not available. enum: - 'NO' - POSSIBLE - UNKNOWN three_d_secure_authentication_response: type: object title: Response of 3D Secure Authentication description: Results of 3D Secure Authentication. properties: authentication_status: $ref: '#/components/schemas/pares_status' description: The outcome of the issuer's authentication. enrollment_status: $ref: '#/components/schemas/enrolled' description: Status of authentication eligibility. card_vault_response: type: object title: Card Vault Response description: The details about a saved Card payment source. properties: id: type: string description: The PayPal-generated ID for the saved payment source. minLength: 1 maxLength: 255 status: title: Vault Status type: string description: The vault status. minLength: 1 maxLength: 255 pattern: ^[0-9A-Z_]+$ x-enumDescriptions: - value: VAULTED description: >- The payment source has been saved in your customer's vault. This vault status reflects `/v3/vault` status. - value: CREATED description: >- DEPRECATED. The payment source has been saved in your customer's vault. This status applies to deprecated integration patterns and will not be returned for v3/vault integrations. - value: APPROVED description: >- Customer has approved the action of saving the specified payment_source into their vault. Use v3/vault/payment-tokens with given setup_token to save the payment source in the vault deprecated: true enum: - VAULTED - CREATED - APPROVED links: $ref: '#/components/schemas/link_description_list' customer: $ref: '#/components/schemas/card_customer' country_code-2: type: string 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.
format: ppaas_common_country_code_v2 maxLength: 2 minLength: 2 pattern: ^([A-Z]{2}|C2)$ products_list: type: array 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. items: $ref: '#/components/schemas/products' minItems: 1 maxItems: 256 paypal_wallet_vault_response: type: object title: PayPal Wallet Vault Response description: The details about a saved PayPal Wallet payment source. properties: id: type: string description: The PayPal-generated ID for the saved payment source. minLength: 1 maxLength: 255 status: title: Vault Status type: string description: The vault status. minLength: 1 maxLength: 255 pattern: ^[0-9A-Z_]+$ x-enumDescriptions: - value: VAULTED description: >- The payment source has been saved in your customer's vault. This vault status reflects `/v3/vault` status. - value: CREATED description: >- DEPRECATED. The payment source has been saved in your customer's vault. This status applies to deprecated integration patterns and will not be returned for v3/vault integrations. - value: APPROVED description: >- Customer has approved the action of saving the specified payment_source into their vault. Use v3/vault/payment-tokens with given setup_token to save the payment source in the vault deprecated: true enum: - VAULTED - CREATED - APPROVED links: $ref: '#/components/schemas/link_description_list' customer: $ref: '#/components/schemas/paypal_wallet_customer' cobranded_card_list: type: array 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). minItems: 0 maxItems: 25 items: $ref: '#/components/schemas/cobranded_card' vault_response: type: object title: Vault Response description: The details about a saved payment source. properties: id: type: string description: The PayPal-generated ID for the saved payment source. minLength: 1 maxLength: 255 status: title: Vault Status type: string description: The vault status. minLength: 1 maxLength: 255 pattern: ^[0-9A-Z_]+$ x-enumDescriptions: - value: VAULTED description: >- The payment source has been saved in your customer's vault. This vault status reflects `/v3/vault` status. - value: CREATED description: >- DEPRECATED. The payment source has been saved in your customer's vault. This status applies to deprecated integration patterns and will not be returned for v3/vault integrations. - value: APPROVED description: >- Customer has approved the action of saving the specified payment_source into their vault. Use v3/vault/payment-tokens with given setup_token to save the payment source in the vault deprecated: true enum: - VAULTED - CREATED - APPROVED customer: type: object title: Customer Information description: >- This object represents a merchant’s customer, allowing them to store contact details, and track all payments associated with the same customer. properties: id: $ref: '#/components/schemas/merchant_partner_customer_id' name: description: The name of the party. type: object title: Name properties: given_name: type: string description: >- When the party is a person, the party's given, or first, name. maxLength: 140 surname: type: string 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. maxLength: 140 links: $ref: '#/components/schemas/link_description_list' account_id: type: string title: PayPal Account Identifier description: The account identifier for a PayPal account. format: ppaas_payer_id_v3 minLength: 13 maxLength: 13 pattern: ^[2-9A-HJ-NP-Z]{13}$ amount_with_breakdown: type: object 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. allOf: - $ref: '#/components/schemas/money' - properties: breakdown: $ref: '#/components/schemas/amount_breakdown' payee: type: object title: Payee description: >- The merchant who receives the funds and fulfills the order. The merchant is also known as the payee. allOf: - $ref: '#/components/schemas/payee_base' - properties: {} payment_instruction: type: object 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. properties: platform_fees: $ref: '#/components/schemas/platform_fee_list' disbursement_mode: $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: type: string 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. minLength: 1 maxLength: 20 pattern: ^.*$ payee_receivable_fx_rate_id: type: string 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. maxLength: 4000 minLength: 1 pattern: ^.*$ item_list: type: array description: An array of items that the customer purchases from the merchant. items: $ref: '#/components/schemas/item' shipping_with_tracking_details: allOf: - $ref: '#/components/schemas/shipping_detail' - properties: 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 title: Phone properties: country_code: type: string 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). minLength: 1 maxLength: 3 pattern: ^[0-9]{1,3}?$ national_number: type: string 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). minLength: 1 maxLength: 14 pattern: ^[0-9]{1,14}?$ required: - country_code - national_number trackers: $ref: '#/components/schemas/tracker_list' - type: object title: Shipping With Tracking Details description: The order shipping details. supplementary_data: title: Supplementary Data type: object 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. properties: card: $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: $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: type: object 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. properties: authorizations: $ref: '#/components/schemas/authorization_with_additional_data_list' captures: $ref: '#/components/schemas/capture_list' refunds: $ref: '#/components/schemas/refund_list' most_recent_error_list: description: >- The error reason code and description that are the reason for the most recent order decline. type: array minItems: 1 maxItems: 10 items: $ref: '#/components/schemas/most_recent_error' store_in_vault_instruction: type: string description: Defines how and when the payment source gets vaulted. minLength: 1 maxLength: 255 pattern: ^[0-9A-Z_]+$ x-enumDescriptions: - value: ON_SUCCESS description: >- Defines that the payment_source will be vaulted only when at least one authorization or capture using that payment_source is successful. enum: - ON_SUCCESS network_transaction: type: object title: Network Transaction description: Reference values used by the card network to identify a transaction. properties: id: type: string minLength: 9 maxLength: 36 pattern: ^[a-zA-Z0-9-_@.:&+=*^'~#!$%()]+$ 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 -. date: type: string minLength: 4 maxLength: 4 pattern: ^[0-9]+$ 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. network: $ref: '#/components/schemas/card_brand' description: Name of the card network through which the transaction was routed. acquirer_reference_number: type: string description: >- Reference ID issued for the card transaction. This ID can be used to track the transaction across processors, card brands and issuing banks. minLength: 1 maxLength: 36 pattern: ^[a-zA-Z0-9]+$ native_app_context: type: object title: App Switch Preferences on Native App description: >- Merchant provided, buyer's native app preferences to app switch to the PayPal consumer app. properties: os_type: type: string readOnly: true description: Operating System type of the device that the buyer is using. minLength: 1 maxLength: 7 pattern: ^[A-Z_]+$ x-enumDescriptions: - value: ANDROID description: Google Android OS. - value: IOS description: Apple OS typically found in Apple mobile devices. - value: OTHER description: Any other OS type. enum: - ANDROID - IOS - OTHER os_version: type: string readOnly: true description: Operating System version of the device that the buyer is using. minLength: 1 maxLength: 64 pattern: ^.*$ mobile_web_context: type: object title: Mobile Web App Switch Context description: >- Buyer's mobile web browser context to app switch to the PayPal consumer app. properties: return_flow: type: string readOnly: true description: >- Merchant preference on how the buyer can navigate back to merchant website post approving the transaction on the PayPal App. minLength: 1 maxLength: 6 pattern: ^[A-Z_]+$ default: AUTO x-enumDescriptions: - value: AUTO description: >- After payment approval in the PayPal App, buyer will automatically be redirected to the merchant website. - value: MANUAL description: >- After payment approval in the PayPal App, buyer will be asked to manually navigate back to the merchant website where they started the transaction from. The buyer is shown a message like 'Return to Merchant' to return to the source where the transaction actually started. enum: - AUTO - MANUAL 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: ^.*$ callback_events_list: type: array description: >- An array of callback events merchant can subscribe to for the corresponding callback url. minItems: 1 maxItems: 5 uniqueItems: true items: $ref: '#/components/schemas/callback_events' currency_code: description: >- The [three-character ISO-4217 currency code](/api/rest/reference/currency-codes/) that identifies the currency. type: string format: ppaas_common_currency_code_v2 minLength: 3 maxLength: 3 merchant_partner_customer_id: type: string description: The unique ID for a customer generated by PayPal. minLength: 1 maxLength: 22 pattern: ^[0-9a-zA-Z_-]+$ pares_status: type: string minLength: 1 maxLength: 255 pattern: ^[0-9A-Z_]+$ description: >- Transactions status result identifier. The outcome of the issuer's authentication. x-enumDescriptions: - value: 'Y' description: Successful authentication. - value: 'N' description: Failed authentication / account not verified / transaction denied. - value: U description: Unable to complete authentication. - value: A description: Successful attempts transaction. - value: C description: Challenge required for authentication. - value: R description: >- Authentication rejected (merchant must not submit for authorization). - value: D description: Challenge required; decoupled authentication confirmed. - value: I description: Informational only; 3DS requestor challenge preference acknowledged. enum: - 'Y' - 'N' - U - A - C - R - D - I enrolled: type: string minLength: 1 maxLength: 255 pattern: ^[0-9A-Z_]+$ description: Status of Authentication eligibility. x-enumDescriptions: - value: 'Y' description: >- Yes. The bank is participating in 3-D Secure protocol and will return the ACSUrl. - value: 'N' description: No. The bank is not participating in 3-D Secure protocol. - value: U description: >- Unavailable. The DS or ACS is not available for authentication at the time of the request. - value: B description: >- Bypass. The merchant authentication rule is triggered to bypass authentication. enum: - 'Y' - 'N' - U - B products: type: string description: This value provides the category of the BIN. minLength: 1 maxLength: 255 cobranded_card: type: object title: cobranded card description: Details about the merchant cobranded card used for order purchase. properties: labels: $ref: '#/components/schemas/labels_list' payee: type: object 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. properties: email_address: $ref: '#/components/schemas/email' description: The email address of merchant. merchant_id: $ref: '#/components/schemas/account_id' description: The encrypted PayPal account ID of the merchant. amount: $ref: '#/components/schemas/money' description: Amount that was charged to the cobranded card. amount_breakdown: type: object description: >- The breakdown of the amount. Breakdown provides details such as total item amount, total tax amount, shipping, handling, insurance, and discounts, if any. title: Amount Breakdown properties: item_total: $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: $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: $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: $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: $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: $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: $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: type: object 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. properties: email_address: $ref: '#/components/schemas/email' description: The email address of merchant. merchant_id: $ref: '#/components/schemas/account_id' description: The encrypted PayPal account ID of the merchant. platform_fee_list: type: array 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. minItems: 0 maxItems: 1 items: $ref: '#/components/schemas/platform_fee' disbursement_mode: type: string title: Disbursement Mode description: The funds that are held on behalf of the merchant. default: INSTANT minLength: 1 maxLength: 16 pattern: ^[A-Z_]+$ x-enumDescriptions: - value: INSTANT description: The funds are released to the merchant immediately. default: INSTANT - value: DELAYED description: >- The funds are held for a finite number of days. The actual duration depends on the region and type of integration. You can release the funds through a referenced payout. Otherwise, the funds disbursed automatically after the specified duration. enum: - INSTANT - DELAYED item: type: object title: Item description: The details for the items to be purchased. properties: name: type: string description: The item name or title. minLength: 1 maxLength: 127 unit_amount: $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: $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: type: string description: The item quantity. Must be a whole number. maxLength: 10 pattern: ^[1-9][0-9]{0,9}$ description: type: string description: The detailed item description. maxLength: 2048 sku: type: string description: The stock keeping unit (SKU) for the item. maxLength: 127 url: type: string format: uri minLength: 1 maxLength: 2048 description: >- The URL to the item being purchased. Visible to buyer and used in buyer experiences. category: type: string description: The item category type. x-enumDescriptions: - value: DIGITAL_GOODS description: >- Goods that are stored, delivered, and used in their electronic format. This value is not currently supported for API callers that leverage the PayPal for Commerce Platform product. - value: PHYSICAL_GOODS description: A tangible item that can be shipped with proof of delivery. - value: DONATION description: >- A contribution or gift for which no good or service is exchanged, usually to a not for profit organization. minLength: 1 maxLength: 20 enum: - DIGITAL_GOODS - PHYSICAL_GOODS - DONATION image_url: type: string format: uri description: >- The URL of the item's image. File type and size restrictions apply. An image that violates these restrictions will not be honored. minLength: 1 maxLength: 2048 pattern: >- ^(https:)([/|.|\w|\s|-])*\.(?:jpg|gif|png|jpeg|JPG|GIF|PNG|JPEG)(\?.*)?$ upc: $ref: '#/components/schemas/universal_product_code' description: The Universal Product Code of the item. billing_plan: $ref: '#/components/schemas/order_billing_plan' required: - name - unit_amount - quantity shipping_detail: type: object description: The shipping details. title: Shipping Details properties: name: description: The name of the party. type: object title: Name properties: full_name: type: string description: When the party is a person, the party's full name. maxLength: 300 email_address: $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: 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 title: Phone properties: country_code: type: string 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). minLength: 1 maxLength: 3 pattern: ^[0-9]{1,3}?$ national_number: type: string 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). minLength: 1 maxLength: 14 pattern: ^[0-9]{1,14}?$ required: - country_code - national_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 minLength: 1 maxLength: 255 pattern: ^[0-9A-Z_]+$ x-enumDescriptions: - value: SHIPPING description: The payer intends to receive the items at a specified address. default: true - value: PICKUP_IN_PERSON description: DEPRECATED. Please use "PICKUP_FROM_PERSON" instead. - value: PICKUP_IN_STORE description: >- The payer intends to pick up the item(s) from the payee's physical store. Also termed as BOPIS, "Buy Online, Pick-up in Store". Seller protection is provided with this option. - value: PICKUP_FROM_PERSON description: >- The payer intends to pick up the item(s) from the payee in person. Also termed as BOPIP, "Buy Online, Pick-up in Person". Seller protection is not available, since the payer is receiving the item from the payee in person, and can validate the item prior to payment. enum: - SHIPPING - PICKUP_IN_PERSON - PICKUP_IN_STORE - PICKUP_FROM_PERSON options: $ref: '#/components/schemas/shipping_option_list' address: 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 title: Portable Postal Address (Medium-Grained) properties: address_line_1: type: string 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. maxLength: 300 address_line_2: type: string description: >- The second line of the address, for example, a suite or apartment number. maxLength: 300 admin_area_2: type: string description: A city, town, or village. Smaller than `admin_area_level_1`. maxLength: 120 admin_area_1: type: string 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: maxLength: 300 postal_code: type: string 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). maxLength: 60 country_code: $ref: '#/components/schemas/country_code' required: - country_code tracker_list: type: array description: An array of trackers for a transaction. items: $ref: '#/components/schemas/tracker' card_supplementary_data: type: object 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. properties: level_2: $ref: '#/components/schemas/level_2_card_processing_data' level_3: $ref: '#/components/schemas/level_3_card_processing_data' risk_supplementary_data: type: object title: Risk Supplementary Data description: >- Additional information necessary to evaluate the risk profile of a transaction. properties: customer: $ref: '#/components/schemas/participant_metadata' authorization_with_additional_data_list: type: array description: >- An array of authorized payments for a purchase unit. A purchase unit can have zero or more authorized payments. items: $ref: '#/components/schemas/authorization_with_additional_data' capture_list: type: array description: >- An array of captured payments for a purchase unit. A purchase unit can have zero or more captured payments. items: $ref: '#/components/schemas/capture' refund_list: type: array description: >- An array of refunds for a purchase unit. A purchase unit can have zero or more refunds. items: $ref: '#/components/schemas/refund' most_recent_error: {} callback_events: type: string minLength: 1 maxLength: 256 pattern: ^[0-9A-Z_]+$ description: CallBack event. x-enumDescriptions: - value: SHIPPING_ADDRESS description: >- When Buyer changes or selects the shipping address on the PayPal/Venmo buyer approval flow , PayPal/Venmo will call merchant with the callback URL to update order totals. - value: SHIPPING_OPTIONS description: >- When Buyer changes or selects the shipping options on the PayPal/Venmo buyer approval flow , PayPal/Venmo will call merchant with the callback URL to update order totals. enum: - SHIPPING_ADDRESS - SHIPPING_OPTIONS labels_list: type: array description: Array of labels for the cobranded card. minItems: 1 maxItems: 25 items: $ref: '#/components/schemas/labels' discount_with_breakdown: type: object title: Discount description: >- The discount amount and currency code. For list of supported currencies and decimal precision, see the PayPal REST APIs Currency Codes. allOf: - $ref: '#/components/schemas/money' - properties: {} platform_fee: type: object 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. properties: amount: $ref: '#/components/schemas/money' description: The fee for this transaction. payee: $ref: '#/components/schemas/payee_base' description: >- The recipient of the fee for this transaction. If you omit this value, the default is the API caller. required: - amount universal_product_code: type: object title: Universal Product Code description: The Universal Product Code of the item. properties: type: title: Universal Product Code Type type: string x-enumDescriptions: - value: UPC-A - value: UPC-B - value: UPC-C - value: UPC-D - value: UPC-E - value: UPC-2 - value: UPC-5 description: The Universal Product Code type. minLength: 1 maxLength: 5 pattern: ^[0-9A-Z_-]+$ enum: - UPC-A - UPC-B - UPC-C - UPC-D - UPC-E - UPC-2 - UPC-5 code: type: string description: The UPC product code of the item. minLength: 6 maxLength: 17 pattern: ^[0-9]{0,17}$ required: - type - code order_billing_plan: title: Billing Plan description: >- Metadata for merchant-managed recurring billing plans. Valid only during the saved payment method token or billing agreement creation. type: object properties: billing_cycles: $ref: '#/components/schemas/billing_cycle_list' setup_fee: $ref: '#/components/schemas/money' description: >- The setup fee for the recurring plan. Ensure its part of the item amount. name: type: string description: Name of the recurring plan. minLength: 1 maxLength: 127 pattern: ^[A-Za-z0-9() +',.:-]+$ required: - billing_cycles shipping_option_list: type: array description: >- An array of shipping options that the payee or merchant offers to the payer to ship or pick up their items. minItems: 0 maxItems: 10 items: $ref: '#/components/schemas/shipping_option' tracker: type: object title: Order Tracker Response. description: The tracking response on creation of tracker. allOf: - properties: id: type: string description: The tracker id. readOnly: true status: $ref: '#/components/schemas/tracker_status' items: $ref: '#/components/schemas/tracker_item_list' links: $ref: '#/components/schemas/definitions-link_description_list' - $ref: '#/components/schemas/activity_timestamps' level_2_card_processing_data: type: object title: Level 2 Card Processing Data 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. properties: invoice_id: type: string 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. minLength: 1 maxLength: 127 pattern: ^[\w‘\-.,":;\!?]*$ tax_total: $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: type: object title: Level 3 Card Processing Data 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. properties: shipping_amount: $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: $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: $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: 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 title: Portable Postal Address (Medium-Grained) properties: address_line_1: type: string 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. maxLength: 300 address_line_2: type: string description: >- The second line of the address, for example, a suite or apartment number. maxLength: 300 admin_area_2: type: string description: A city, town, or village. Smaller than `admin_area_level_1`. maxLength: 120 admin_area_1: type: string 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: maxLength: 300 postal_code: type: string 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). maxLength: 60 country_code: $ref: '#/components/schemas/country_code' required: - country_code ships_from_postal_code: type: string description: Use this field to specify the postal code of the shipping location. minLength: 1 maxLength: 60 pattern: ^[a-zA-Z0-9_'.-]*$ line_items: $ref: '#/components/schemas/line_item_list' participant_metadata: type: object title: Participant metadata description: Profile information of the sender or receiver. properties: ip_address: $ref: '#/components/schemas/ip_address' description: >- The consumer's IP address, which can be represented in either IPv4 or IPv6 format. authorization_with_additional_data: type: object 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. allOf: - $ref: '#/components/schemas/authorization' - properties: processor_response: $ref: '#/components/schemas/processor_response' description: The processor response for card transactions. readOnly: true capture: type: object title: Capture description: A captured payment. allOf: - $ref: '#/components/schemas/capture_status' - properties: id: description: The PayPal-generated ID for the captured payment. type: string readOnly: true amount: $ref: '#/components/schemas/money' 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 readOnly: true custom_id: type: string description: >- The API caller-provided external ID. Used to reconcile API caller-initiated transactions with PayPal transactions. Appears in transaction and settlement reports. maxLength: 255 network_transaction_reference: $ref: '#/components/schemas/network_transaction' seller_protection: $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: $ref: '#/components/schemas/seller_receivable_breakdown' readOnly: true disbursement_mode: $ref: '#/components/schemas/disbursement_mode' links: $ref: '#/components/schemas/definitions-link_description_list' processor_response: $ref: '#/components/schemas/processor_response' description: >- An object that provides additional processor information for a direct credit card transaction. - $ref: '#/components/schemas/activity_timestamps' refund: type: object title: Refund description: The refund information. allOf: - $ref: '#/components/schemas/refund_status' - properties: id: description: The PayPal-generated ID for the refund. type: string readOnly: true amount: $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 readOnly: true custom_id: type: string description: >- The API caller-provided external ID. Used to reconcile API caller-initiated transactions with PayPal transactions. Appears in transaction and settlement reports. minLength: 1 maxLength: 255 pattern: ^[A-Za-z0-9-_.,]*$ acquirer_reference_number: type: string description: >- Reference ID issued for the card transaction. This ID can be used to track the transaction across processors, card brands and issuing banks. 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 readOnly: true seller_payable_breakdown: $ref: '#/components/schemas/seller_payable_breakdown' payer: $ref: '#/components/schemas/payee_base' description: The details associated with the merchant for this transaction. readOnly: true links: $ref: '#/components/schemas/definitions-link_description_list' - $ref: '#/components/schemas/activity_timestamps' labels: type: string description: Label for the cobranded card. minLength: 1 maxLength: 256 billing_cycle_list: type: array 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. minItems: 1 maxItems: 3 items: $ref: '#/components/schemas/billing_cycle' shipping_option: type: object title: Shipping Option description: >- The options that the payee or merchant offers to the payer to ship or pick up their items. properties: id: type: string description: A unique ID that identifies a payer-selected shipping option. maxLength: 127 label: type: string 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. maxLength: 127 type: $ref: '#/components/schemas/shipping_type' description: A classification for the method of purchase fulfillment. amount: $ref: '#/components/schemas/money' description: The shipping cost for the selected option. selected: type: boolean 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`. required: - id - label - selected tracker_status: type: string title: Tracker Status description: The status of the item shipment. minLength: 1 maxLength: 64 pattern: ^[0-9A-Z_]+$ x-enumDescriptions: - value: CANCELLED description: >- The shipment was cancelled and the tracking number no longer applies. - value: SHIPPED description: >- The merchant has assigned a tracking number to the items being shipped from the Order. This does not correspond to the carrier's actual status for the shipment. The latest status of the parcel must be retrieved from the carrier. enum: - CANCELLED - SHIPPED tracker_item_list: type: array description: An array of details of items in the shipment. items: $ref: '#/components/schemas/tracker_item' definitions-link_description_list: description: >- An array of related [HATEOAS links](/docs/api/reference/api-responses/#hateoas-links). type: array readOnly: true items: $ref: '#/components/schemas/link_description' line_item_list: type: array 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. minItems: 1 maxItems: 100 items: $ref: '#/components/schemas/line_item' ip_address: type: string 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. format: ppaas_ip_address_v1 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*$ authorization: type: object title: Authorization description: The authorized payment transaction. allOf: - $ref: '#/components/schemas/authorization_status' - properties: id: description: The PayPal-generated ID for the authorized payment. type: string readOnly: true amount: $ref: '#/components/schemas/money' 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 readOnly: true custom_id: type: string description: >- The API caller-provided external ID. Used to reconcile API caller-initiated transactions with PayPal transactions. Appears in transaction and settlement reports. maxLength: 255 network_transaction_reference: $ref: '#/components/schemas/network_transaction' seller_protection: $ref: '#/components/schemas/seller_protection' readOnly: true expiration_time: $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: $ref: '#/components/schemas/definitions-link_description_list' - $ref: '#/components/schemas/activity_timestamps' processor_response: type: object title: Processor Response description: >- The processor response information for payment requests, such as direct credit card transactions. properties: avs_code: description: >- The address verification code for Visa, Discover, Mastercard, or American Express transactions. type: string readOnly: true x-enumDescriptions: - value: A description: >- For Visa, Mastercard, or Discover transactions, the address matches but the zip code does not match. For American Express transactions, the card holder address is correct. - value: B description: >- For Visa, Mastercard, or Discover transactions, the address matches. International A. - value: C description: >- For Visa, Mastercard, or Discover transactions, no values match. International N. - value: D description: >- For Visa, Mastercard, or Discover transactions, the address and postal code match. International X. - value: E description: >- For Visa, Mastercard, or Discover transactions, not allowed for Internet or phone transactions. For American Express card holder, the name is incorrect but the address and postal code match. - value: F description: >- For Visa, Mastercard, or Discover transactions, the address and postal code match. UK-specific X. For American Express card holder, the name is incorrect but the address matches. - value: G description: >- For Visa, Mastercard, or Discover transactions, global is unavailable. Nothing matches. - value: I description: >- For Visa, Mastercard, or Discover transactions, international is unavailable. Not applicable. - value: M description: >- For Visa, Mastercard, or Discover transactions, the address and postal code match. For American Express card holder, the name, address, and postal code match. - value: 'N' description: >- For Visa, Mastercard, or Discover transactions, nothing matches. For American Express card holder, the address and postal code are both incorrect. - value: P description: >- For Visa, Mastercard, or Discover transactions, postal international Z. Postal code only. - value: R description: >- For Visa, Mastercard, or Discover transactions, re-try the request. For American Express, the system is unavailable. - value: S description: >- For Visa, Mastercard, Discover, or American Express, the service is not supported. - value: U description: >- For Visa, Mastercard, or Discover transactions, the service is unavailable. For American Express, information is not available. For Maestro, the address is not checked or the acquirer had no response. The service is not available. - value: W description: >- For Visa, Mastercard, or Discover transactions, whole ZIP code. For American Express, the card holder name, address, and postal code are all incorrect. - value: X description: >- For Visa, Mastercard, or Discover transactions, exact match of the address and the nine-digit ZIP code. For American Express, the card holder name, address, and postal code are all incorrect. - value: 'Y' description: >- For Visa, Mastercard, or Discover transactions, the address and five-digit ZIP code match. For American Express, the card holder address and postal code are both correct. - value: Z description: >- For Visa, Mastercard, or Discover transactions, the five-digit ZIP code matches but no address. For American Express, only the card holder postal code is correct. - value: 'Null' description: For Maestro, no AVS response was obtained. - value: '0' description: For Maestro, all address information matches. - value: '1' description: For Maestro, none of the address information matches. - value: '2' description: For Maestro, part of the address information matches. - value: '3' description: >- For Maestro, the merchant did not provide AVS information. It was not processed. - value: '4' description: >- For Maestro, the address was not checked or the acquirer had no response. The service is not available. 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' cvv_code: description: >- The card verification value code for for Visa, Discover, Mastercard, or American Express. type: string readOnly: true x-enumDescriptions: - value: E description: >- For Visa, Mastercard, Discover, or American Express, error - unrecognized or unknown response. - value: I description: >- For Visa, Mastercard, Discover, or American Express, invalid or null. - value: M description: >- For Visa, Mastercard, Discover, or American Express, the CVV2/CSC matches. - value: 'N' description: >- For Visa, Mastercard, Discover, or American Express, the CVV2/CSC does not match. - value: P description: >- For Visa, Mastercard, Discover, or American Express, it was not processed. - value: S description: >- For Visa, Mastercard, Discover, or American Express, the service is not supported. - value: U description: >- For Visa, Mastercard, Discover, or American Express, unknown - the issuer is not certified. - value: X description: >- For Visa, Mastercard, Discover, or American Express, no response. For Maestro, the service is not available. - value: All others description: For Visa, Mastercard, Discover, or American Express, error. - value: '0' description: For Maestro, the CVV2 matched. - value: '1' description: For Maestro, the CVV2 did not match. - value: '2' description: >- For Maestro, the merchant has not implemented CVV2 code handling. - value: '3' description: >- For Maestro, the merchant has indicated that CVV2 is not present on card. - value: '4' description: For Maestro, the service is not available. enum: - E - I - M - 'N' - P - S - U - X - All others - '0' - '1' - '2' - '3' - '4' response_code: description: Processor response code for the non-PayPal payment processor errors. type: string readOnly: true x-enumDescriptions: - value: '0000' description: APPROVED. - value: 00N7 description: CVV2_FAILURE_POSSIBLE_RETRY_WITH_CVV. - value: '0100' description: REFERRAL. - value: '0390' description: ACCOUNT_NOT_FOUND. - value: '0500' description: DO_NOT_HONOR. - value: '0580' description: UNAUTHORIZED_TRANSACTION. - value: '0800' description: BAD_RESPONSE_REVERSAL_REQUIRED. - value: '0880' description: CRYPTOGRAPHIC_FAILURE. - value: '0890' description: UNACCEPTABLE_PIN. - value: '0960' description: SYSTEM_MALFUNCTION. - value: 0R00 description: CANCELLED_PAYMENT. - value: '1000' description: PARTIAL_AUTHORIZATION. - value: 10BR description: ISSUER_REJECTED. - value: '1300' description: INVALID_DATA_FORMAT. - value: '1310' description: INVALID_AMOUNT. - value: '1312' description: INVALID_TRANSACTION_CARD_ISSUER_ACQUIRER. - value: '1317' description: INVALID_CAPTURE_DATE. - value: '1320' description: INVALID_CURRENCY_CODE. - value: '1330' description: INVALID_ACCOUNT. - value: '1335' description: INVALID_ACCOUNT_RECURRING. - value: '1340' description: INVALID_TERMINAL. - value: '1350' description: INVALID_MERCHANT. - value: '1352' description: RESTRICTED_OR_INACTIVE_ACCOUNT. - value: '1360' description: BAD_PROCESSING_CODE. - value: '1370' description: INVALID_MCC. - value: '1380' description: INVALID_EXPIRATION. - value: '1382' description: INVALID_CARD_VERIFICATION_VALUE. - value: '1384' description: INVALID_LIFE_CYCLE_OF_TRANSACTION. - value: '1390' description: INVALID_ORDER. - value: '1393' description: TRANSACTION_CANNOT_BE_COMPLETED. - value: '5100' description: GENERIC_DECLINE. - value: '5110' description: CVV2_FAILURE. - value: '5120' description: INSUFFICIENT_FUNDS. - value: '5130' description: INVALID_PIN. - value: '5135' description: DECLINED_PIN_TRY_EXCEEDED. - value: '5140' description: CARD_CLOSED. - value: '5150' description: >- PICKUP_CARD_SPECIAL_CONDITIONS. Try using another card. Do not retry the same card. - value: '5160' description: UNAUTHORIZED_USER. - value: '5170' description: AVS_FAILURE. - value: '5180' description: >- INVALID_OR_RESTRICTED_CARD. Try using another card. Do not retry the same card. - value: '5190' description: SOFT_AVS. - value: '5200' description: DUPLICATE_TRANSACTION. - value: '5210' description: INVALID_TRANSACTION. - value: '5400' description: EXPIRED_CARD. - value: '5500' description: INCORRECT_PIN_REENTER. - value: '5650' description: DECLINED_SCA_REQUIRED. - value: '5700' description: >- TRANSACTION_NOT_PERMITTED. Outside of scope of accepted business. - value: '5710' description: TX_ATTEMPTS_EXCEED_LIMIT. - value: '5800' description: REVERSAL_REJECTED. - value: '5900' description: INVALID_ISSUE. - value: '5910' description: ISSUER_NOT_AVAILABLE_NOT_RETRIABLE. - value: '5920' description: ISSUER_NOT_AVAILABLE_RETRIABLE. - value: '5930' description: CARD_NOT_ACTIVATED. - value: '5950' description: >- DECLINED_DUE_TO_UPDATED_ACCOUNT. External decline as an updated card has been issued. - value: '6300' description: ACCOUNT_NOT_ON_FILE. - value: '7600' description: APPROVED_NON_CAPTURE. - value: '7700' description: ERROR_3DS. - value: '7710' description: AUTHENTICATION_FAILED. - value: '7800' description: BIN_ERROR. - value: '7900' description: PIN_ERROR. - value: '8000' description: PROCESSOR_SYSTEM_ERROR. - value: '8010' description: HOST_KEY_ERROR. - value: '8020' description: CONFIGURATION_ERROR. - value: '8030' description: UNSUPPORTED_OPERATION. - value: '8100' description: FATAL_COMMUNICATION_ERROR. - value: '8110' description: RETRIABLE_COMMUNICATION_ERROR. - value: '8220' description: SYSTEM_UNAVAILABLE. - value: '9100' description: DECLINED_PLEASE_RETRY. Retry. - value: '9500' description: >- SUSPECTED_FRAUD. Try using another card. Do not retry the same card. - value: '9510' description: SECURITY_VIOLATION. - value: '9520' description: >- LOST_OR_STOLEN. Try using another card. Do not retry the same card. - value: '9530' description: >- HOLD_CALL_CENTER. The merchant must call the number on the back of the card. POS scenario. - value: '9540' description: REFUSED_CARD. - value: '9600' description: UNRECOGNIZED_RESPONSE_CODE. - value: PCNR description: CONTINGENCIES_NOT_RESOLVED. - value: PCVV description: CVV_FAILURE. - value: PP06 description: ACCOUNT_CLOSED. A previously open account is now closed - value: PPRN description: REATTEMPT_NOT_PERMITTED. - value: PPAD description: BILLING_ADDRESS. - value: PPAB description: ACCOUNT_BLOCKED_BY_ISSUER. - value: PPAE description: AMEX_DISABLED. - value: PPAG description: ADULT_GAMING_UNSUPPORTED. - value: PPAI description: AMOUNT_INCOMPATIBLE. - value: PPAR description: AUTH_RESULT. - value: PPAU description: MCC_CODE. - value: PPAV description: ARC_AVS. - value: PPAX description: AMOUNT_EXCEEDED. - value: PPBG description: BAD_GAMING. - value: PPC2 description: ARC_CVV. - value: PPCE description: CE_REGISTRATION_INCOMPLETE. - value: PPCO description: COUNTRY. - value: PPCR description: CREDIT_ERROR. - value: PPCT description: CARD_TYPE_UNSUPPORTED. - value: PPCU description: CURRENCY_USED_INVALID. - value: PPD3 description: SECURE_ERROR_3DS. - value: PPDC description: DCC_UNSUPPORTED. - value: PPDI description: DINERS_REJECT. - value: PPDV description: AUTH_MESSAGE. - value: PPDT description: DECLINE_THRESHOLD_BREACH. - value: PPEF description: EXPIRED_FUNDING_INSTRUMENT. - value: PPEL description: EXCEEDS_FREQUENCY_LIMIT. - value: PPER description: INTERNAL_SYSTEM_ERROR. - value: PPEX description: EXPIRY_DATE. - value: PPFE description: FUNDING_SOURCE_ALREADY_EXISTS. - value: PPFI description: INVALID_FUNDING_INSTRUMENT. - value: PPFR description: RESTRICTED_FUNDING_INSTRUMENT. - value: PPFV description: FIELD_VALIDATION_FAILED. - value: PPGR description: GAMING_REFUND_ERROR. - value: PPH1 description: H1_ERROR. - value: PPIF description: IDEMPOTENCY_FAILURE. - value: PPII description: INVALID_INPUT_FAILURE. - value: PPIM description: ID_MISMATCH. - value: PPIT description: INVALID_TRACE_ID. - value: PPLR description: LATE_REVERSAL. - value: PPLS description: LARGE_STATUS_CODE. - value: PPMB description: MISSING_BUSINESS_RULE_OR_DATA. - value: PPMC description: BLOCKED_Mastercard. - value: PPMD description: DEPRECATED The PPMD value has been deprecated. - value: PPNC description: NOT_SUPPORTED_NRC. - value: PPNL description: EXCEEDS_NETWORK_FREQUENCY_LIMIT. - value: PPNM description: NO_MID_FOUND. - value: PPNT description: NETWORK_ERROR. - value: PPPH description: NO_PHONE_FOR_DCC_TRANSACTION. - value: PPPI description: INVALID_PRODUCT. - value: PPPM description: INVALID_PAYMENT_METHOD. - value: PPQC description: QUASI_CASH_UNSUPPORTED. - value: PPRE description: UNSUPPORT_REFUND_ON_PENDING_BC. - value: PPRF description: INVALID_PARENT_TRANSACTION_STATUS. - value: PPRR description: MERCHANT_NOT_REGISTERED. - value: PPS0 description: BANKAUTH_ROW_MISMATCH. - value: PPS1 description: BANKAUTH_ROW_SETTLED. - value: PPS2 description: BANKAUTH_ROW_VOIDED. - value: PPS3 description: BANKAUTH_EXPIRED. - value: PPS4 description: CURRENCY_MISMATCH. - value: PPS5 description: CREDITCARD_MISMATCH. - value: PPS6 description: AMOUNT_MISMATCH. - value: PPSC description: ARC_SCORE. - value: PPSD description: STATUS_DESCRIPTION. - value: PPSE description: AMEX_DENIED. - value: PPTE description: VERIFICATION_TOKEN_EXPIRED. - value: PPTF description: INVALID_TRACE_REFERENCE. - value: PPTI description: INVALID_TRANSACTION_ID. - value: PPTR description: VERIFICATION_TOKEN_REVOKED. - value: PPTT description: TRANSACTION_TYPE_UNSUPPORTED. - value: PPTV description: INVALID_VERIFICATION_TOKEN. - value: PPUA description: USER_NOT_AUTHORIZED. - value: PPUC description: CURRENCY_CODE_UNSUPPORTED. - value: PPUE description: UNSUPPORT_ENTITY. - value: PPUI description: UNSUPPORT_INSTALLMENT. - value: PPUP description: UNSUPPORT_POS_FLAG. - value: PPUR description: UNSUPPORTED_REVERSAL. - value: PPVC description: VALIDATE_CURRENCY. - value: PPVE description: VALIDATION_ERROR. - value: PPVT description: VIRTUAL_TERMINAL_UNSUPPORTED. 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 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 readOnly: true x-enumDescriptions: - value: '01' description: >- For Mastercard, expired card account upgrade or portfolio sale conversion. Obtain new account information before next billing cycle. - value: '02' description: >- For Mastercard, over credit limit or insufficient funds. Retry the transaction 72 hours later. For Visa, the card holder wants to stop only one specific payment in the recurring payment relationship. The merchant must NOT resubmit the same transaction. The merchant can continue the billing process in the subsequent billing period. - value: '03' description: >- For Mastercard, account closed as fraudulent. Obtain another type of payment from customer due to account being closed or fraud. Possible reason: Account closed as fraudulent. For Visa, the card holder wants to stop all recurring payment transactions for a specific merchant. Stop recurring payment requests. - value: '04' description: >- For Mastercard, token requirements not fulfilled for this token type. - value: '21' description: >- For Mastercard, the card holder has been unsuccessful at canceling recurring payment through merchant. Stop recurring payment requests. For Visa, all recurring payments were canceled for the card number requested. Stop recurring payment requests. - value: '22' description: For Mastercard, merchant does not qualify for product code. - value: '24' description: For Mastercard, retry after 1 hour. - value: '25' description: For Mastercard, retry after 24 hours. - value: '26' description: For Mastercard, retry after 2 days. - value: '27' description: For Mastercard, retry after 4 days. - value: '28' description: For Mastercard, retry after 6 days. - value: '29' description: For Mastercard, retry after 8 days. - value: '30' description: For Mastercard, retry after 10 days . - value: '40' description: For Mastercard, consumer non-reloadable prepaid card. - value: '43' description: For Mastercard, consumer multi-use virtual card number. enum: - '01' - '02' - '03' - '04' - '21' - '22' - '24' - '25' - '26' - '27' - '28' - '29' - '30' - '40' - '43' capture_status: type: object title: Capture Status With Details description: The status and status details of a captured payment. properties: status: title: Capture Status description: The status of the captured payment. type: string x-enumDescriptions: - value: COMPLETED description: >- The funds for this captured payment were credited to the payee's PayPal account. - value: DECLINED description: The funds could not be captured. - value: PARTIALLY_REFUNDED description: >- An amount less than this captured payment's amount was partially refunded to the payer. - value: PENDING description: >- The funds for this captured payment was not yet credited to the payee's PayPal account. For more information, see status.details. - value: REFUNDED description: >- An amount greater than or equal to this captured payment's amount was refunded to the payer. - value: FAILED description: There was an error while capturing payment. readOnly: true enum: - COMPLETED - DECLINED - PARTIALLY_REFUNDED - PENDING - REFUNDED - FAILED status_details: $ref: '#/components/schemas/capture_status_details' description: The details of the captured payment status. readOnly: true seller_protection: type: object description: >- The level of protection offered as defined by [PayPal Seller Protection for Merchants](https://www.paypal.com/us/webapps/mpp/security/seller-protection). title: Seller Protection properties: status: title: Seller Protection Status type: string 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). x-enumDescriptions: - value: ELIGIBLE description: >- Your PayPal balance remains intact if the customer claims that they did not receive an item or the account holder claims that they did not authorize the payment. - value: PARTIALLY_ELIGIBLE description: >- Your PayPal balance remains intact if the customer claims that they did not receive an item. - value: NOT_ELIGIBLE description: This transaction is not eligible for seller protection. readOnly: true enum: - ELIGIBLE - PARTIALLY_ELIGIBLE - NOT_ELIGIBLE dispute_categories: $ref: '#/components/schemas/dispute_categories_list' seller_receivable_breakdown: type: object title: Seller Receivable Breakdown description: >- The detailed breakdown of the capture activity. This is not available for transactions that are in pending state. properties: gross_amount: $ref: '#/components/schemas/money' description: >- The amount for this captured payment in the currency of the transaction. paypal_fee: $ref: '#/components/schemas/money' description: >- The applicable fee for this captured payment in the currency of the transaction. paypal_fee_in_receivable_currency: $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: $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: $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: $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: $ref: '#/components/schemas/definitions-platform_fee_list' required: - gross_amount refund_status: type: object description: The refund status with details. title: Refund Status With Details properties: status: title: Refund Status With Details description: The status of the refund. type: string x-enumDescriptions: - value: CANCELLED description: The refund was cancelled. - value: FAILED description: The refund could not be processed. - value: PENDING description: >- The refund is pending. For more information, see status_details.reason. - value: COMPLETED description: >- The funds for this transaction were debited to the customer's account. readOnly: true enum: - CANCELLED - FAILED - PENDING - COMPLETED status_details: $ref: '#/components/schemas/refund_status_details' description: The details of the refund status. readOnly: true seller_payable_breakdown: description: The breakdown of the refund. type: object title: Seller Payable Breakdown properties: gross_amount: $ref: '#/components/schemas/money' description: The amount that the payee refunded to the payer. readOnly: true paypal_fee: $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: $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: $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: $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: $ref: '#/components/schemas/refund_definitions-platform_fee_list' net_amount_breakdown: $ref: '#/components/schemas/net_amount_breakdown_item_list' total_refunded_amount: $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. readOnly: true 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 properties: tenure_type: type: string description: >- The tenure type of the billing cycle identifies if the billing cycle is a trial(free or discounted) or regular billing cycle. minLength: 1 maxLength: 24 pattern: ^[A-Z_]+$ x-enumDescriptions: - value: REGULAR description: >- A regular billing cycle to identify recurring charges for the billing agreement. - value: TRIAL description: >- A trial billing cycle to identify free or discounted charge for the billing agreement. Free trails will not have a price object in pricing scheme where as a discounted trial would have a discounted price compared to regular billing cycle. enum: - REGULAR - TRIAL pricing_scheme: $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. frequency: $ref: '#/components/schemas/frequency' description: The frequency details for this billing cycle. total_cycles: type: integer 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). minimum: 0 maximum: 999 default: 1 format: int32 sequence: type: integer 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. minimum: 1 maximum: 3 default: 1 format: int32 start_date: $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. required: - tenure_type shipping_type: type: string title: Shipping Type description: A classification for the method of purchase fulfillment. x-enumDescriptions: - value: SHIPPING description: The payer intends to receive the items at a specified address. default: true - value: PICKUP description: >- DEPRECATED. To ensure that seller protection is correctly assigned, please use 'PICKUP_IN_STORE' or 'PICKUP_FROM_PERSON' instead. Currently, this field indicates that the payer intends to pick up the items at a specified address (ie. a store address). - value: PICKUP_IN_STORE description: >- The payer intends to pick up the item(s) from the payee's physical store. Also termed as BOPIS, "Buy Online, Pick-up in Store". Seller protection is provided with this option. - value: PICKUP_FROM_PERSON description: >- The payer intends to pick up the item(s) from the payee in person. Also termed as BOPIP, "Buy Online, Pick-up in Person". Seller protection is not available, since the payer is receiving the item from the payee in person, and can validate the item prior to payment. enum: - SHIPPING - PICKUP - PICKUP_IN_STORE - PICKUP_FROM_PERSON tracker_item: type: object title: Tracker Item description: The details of the items in the shipment. properties: name: type: string description: The item name or title. minLength: 1 maxLength: 127 quantity: type: string description: The item quantity. Must be a whole number. minLength: 1 maxLength: 10 pattern: ^[1-9][0-9]{0,9}$ sku: type: string description: >- The stock keeping unit (SKU) for the item. This can contain unicode characters. minLength: 1 maxLength: 127 url: type: string format: uri minLength: 1 maxLength: 2048 description: >- The URL to the item being purchased. Visible to buyer and used in buyer experiences. image_url: type: string format: uri description: >- The URL of the item's image. File type and size restrictions apply. An image that violates these restrictions will not be honored. minLength: 1 maxLength: 2048 pattern: ^(https:)([/|.|\w|\s|-])*\.(?:jpg|gif|png|jpeg|JPG|GIF|PNG|JPEG) upc: $ref: '#/components/schemas/universal_product_code' description: The Universal Product Code of the item. line_item: type: object 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. properties: name: type: string description: The item name or title. minLength: 1 maxLength: 127 quantity: type: string description: The item quantity. Must be a whole number. maxLength: 10 pattern: ^[1-9][0-9]{0,9}$ description: type: string description: The detailed item description. maxLength: 2048 sku: type: string description: The stock keeping unit (SKU) for the item. maxLength: 127 url: type: string format: uri minLength: 1 maxLength: 2048 description: >- The URL to the item being purchased. Visible to buyer and used in buyer experiences. image_url: type: string format: uri description: >- The URL of the item's image. File type and size restrictions apply. An image that violates these restrictions will not be honored. minLength: 1 maxLength: 2048 pattern: >- ^(https:)([/|.|\w|\s|-])*\.(?:jpg|gif|png|jpeg|JPG|GIF|PNG|JPEG)(\?.*)?$ upc: $ref: '#/components/schemas/universal_product_code' description: The Universal Product Code of the item. billing_plan: $ref: '#/components/schemas/order_billing_plan' unit_amount: $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: $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: type: string 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. minLength: 1 maxLength: 12 pattern: ^[a-zA-Z0-9_'.-]*$ discount_amount: $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: $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: type: string 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). minLength: 1 maxLength: 12 pattern: ^[a-zA-Z0-9_'.-]*$ required: - name - quantity authorization_status: type: object title: Authorization Status With Details description: The status fields and status details for an authorized payment. properties: status: title: Authorization Status description: The status for the authorized payment. type: string readOnly: true x-enumDescriptions: - value: CREATED description: >- The authorized payment is created. No captured payments have been made for this authorized payment. - value: CAPTURED description: >- The authorized payment has one or more captures against it. The sum of these captured payments is greater than the amount of the original authorized payment. - value: DENIED description: PayPal cannot authorize funds for this authorized payment. - value: PARTIALLY_CAPTURED description: >- A captured payment was made for the authorized payment for an amount that is less than the amount of the original authorized payment. - value: VOIDED description: >- The authorized payment was voided. No more captured payments can be made against this authorized payment. - value: PENDING description: >- The created authorization is in pending state. For more information, see status.details. enum: - CREATED - CAPTURED - DENIED - PARTIALLY_CAPTURED - VOIDED - PENDING status_details: $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 minLength: 1 maxLength: 64 pattern: ^[A-Z_]+$ x-enumDescriptions: - value: BUYER_COMPLAINT description: >- The payer initiated a dispute for this captured payment with PayPal. - value: CHARGEBACK description: >- The captured funds were reversed in response to the payer disputing this captured payment with the issuer of the financial instrument used to pay for this captured payment. - value: ECHECK description: The payer paid by an eCheck that has not yet cleared. - value: INTERNATIONAL_WITHDRAWAL description: >- Visit your online account. In your **Account Overview**, accept and deny this payment. - value: OTHER description: >- No additional specific reason can be provided. For more information about this captured payment, visit your account online or contact PayPal. - value: PENDING_REVIEW description: The captured payment is pending manual review. - value: RECEIVING_PREFERENCE_MANDATES_MANUAL_ACTION description: >- The payee has not yet set up appropriate receiving preferences for their account. For more information about how to accept or deny this payment, visit your account online. This reason is typically offered in scenarios such as when the currency of the captured payment is different from the primary holding currency of the payee. - value: REFUNDED description: The captured funds were refunded. - value: TRANSACTION_APPROVED_AWAITING_FUNDING description: >- The payer must send the funds for this captured payment. This code generally appears for manual EFTs. - value: UNILATERAL description: The payee does not have a PayPal account. - value: VERIFICATION_REQUIRED description: The payee's PayPal account is not verified. - value: DECLINED_BY_RISK_FRAUD_FILTERS description: Risk Filter set by the payee failed for the transaction. 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 dispute_categories_list: type: array description: An array of conditions that are covered for the transaction. items: $ref: '#/components/schemas/dispute_categories' readOnly: true exchange_rate: description: >- The exchange rate that determines the amount to convert from one currency to another currency. type: object title: Exchange Rate properties: source_currency: $ref: '#/components/schemas/currency_code' description: The source currency from which to convert an amount. target_currency: $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 readOnly: true definitions-platform_fee_list: type: array description: >- An array of platform or partner fees, commissions, or brokerage fees that associated with the captured payment. minItems: 0 maxItems: 1 items: $ref: '#/components/schemas/platform_fee' 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 x-enumDescriptions: - value: ECHECK description: >- The customer's account is funded through an eCheck, which has not yet cleared. enum: - ECHECK refund_definitions-platform_fee_list: type: array description: >- An array of platform or partner fees, commissions, or brokerage fees for the refund. minItems: 0 maxItems: 1 items: $ref: '#/components/schemas/platform_fee' net_amount_breakdown_item_list: type: array 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. items: $ref: '#/components/schemas/net_amount_breakdown_item' readOnly: true pricing_scheme: title: Pricing Scheme description: The pricing scheme details. type: object properties: price: $ref: '#/components/schemas/money' description: The price the customer will be charged based on the pricing model pricing_model: type: string description: The pricing model for the billing cycle. minLength: 1 maxLength: 24 pattern: ^[A-Z_]+$ x-enumDescriptions: - value: FIXED description: >- A fixed pricing scheme where the customer is charged a fixed amount. - value: VARIABLE description: >- A variable pricing scheme where the customer is charged a variable amount. - value: AUTO_RELOAD description: >- A auto-reload pricing scheme where the customer is charged a fixed amount for reload. enum: - FIXED - VARIABLE - AUTO_RELOAD reload_threshold_amount: $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. required: - pricing_model frequency: {} 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 minLength: 1 maxLength: 64 pattern: ^[A-Z_]+$ x-enumDescriptions: - value: PENDING_REVIEW description: Authorization is pending manual review. - value: DECLINED_BY_RISK_FRAUD_FILTERS description: Risk Filter set by the payee failed for the transaction. enum: - PENDING_REVIEW - DECLINED_BY_RISK_FRAUD_FILTERS dispute_categories: type: string description: The condition that is covered for the transaction. x-enumDescriptions: - value: ITEM_NOT_RECEIVED description: The payer paid for an item that they did not receive. - value: UNAUTHORIZED_TRANSACTION description: The payer did not authorize the payment. enum: - ITEM_NOT_RECEIVED - UNAUTHORIZED_TRANSACTION net_amount_breakdown_item: type: object title: Net Amount Breakdown Item 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. properties: payable_amount: $ref: '#/components/schemas/money' description: The net amount debited from the merchant's PayPal account. readOnly: true converted_amount: $ref: '#/components/schemas/money' description: The converted payable amount. readOnly: true exchange_rate: $ref: '#/components/schemas/exchange_rate' description: >- The exchange rate that determines the amount that was debited from the merchant's PayPal account. readOnly: true responses: default: description: The default response. content: application/json: schema: $ref: '#/components/schemas/error_default' securitySchemes: Oauth2: type: oauth2 description: Oauth 2.0 authentication flows: clientCredentials: tokenUrl: /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 ````