openapi: 3.2.0 info: title: Payment Method Tokens description: The Payment Method Tokens API saves payment methods so payers don't have to enter details for future transactions. Payers can check out faster or pay without being present after they agree to save a payment method.

The API associates a payment method with a temporary setup token. Pass the setup token to the API to exchange the setup token for a permanent token.

The permanent token represents a payment method that's saved to the vault. This token can be used repeatedly for checkout or recurring transactions such as subscriptions.

The Payment Method Tokens API is available in the US only. version: "3.5" paths: /v3/vault/payment-tokens: post: description: Creates a Payment Token from the given payment source and adds it to the Vault of the associated customer. summary: Create payment token for a given payment source operationId: payment-tokens.create responses: "200": description: Idempotent response for a successful creation of payment token. content: application/json: schema: $ref: "#/components/schemas/payment_token_response" "201": description: A successful creation of payment token. content: application/json: schema: $ref: "#/components/schemas/payment_token_response" "400": description: Request is not well-formed, syntactically incorrect, or violates schema. content: application/json: schema: $ref: "#/components/schemas/error" "403": description: Authorization failed due to insufficient permissions. content: application/json: schema: $ref: "#/components/schemas/error" "404": description: Request contains reference to resources that do not exist. content: application/json: schema: $ref: "#/components/schemas/error" "422": description: The requested action could not be performed, semantically incorrect, or failed business validation. content: application/json: schema: $ref: "#/components/schemas/error" "500": description: An internal server error has occurred. content: application/json: schema: $ref: "#/components/schemas/error" parameters: - $ref: "#/components/parameters/content_type" - $ref: "#/components/parameters/paypal_request_id" requestBody: content: application/json: schema: $ref: "#/components/schemas/payment_token_request" description: Payment Token creation with a financial instrument and an optional customer_id. required: true security: - Oauth2: - https://uri.paypal.com/services/vault/payment-tokens/readwrite tags: - payment-tokens get: description: Returns all payment tokens for a customer. summary: List all payment tokens operationId: customer.payment-tokens.get responses: "200": description: Successful execution. content: application/json: schema: $ref: "#/components/schemas/customer_vault_payment_tokens_response" "400": description: Request is not well-formed, syntactically incorrect, or violates schema. content: application/json: schema: $ref: "#/components/schemas/error" "403": description: Authorization failed due to insufficient permissions. content: application/json: schema: $ref: "#/components/schemas/error" "500": description: An internal server error has occurred. content: application/json: schema: $ref: "#/components/schemas/error" parameters: - $ref: "#/components/parameters/customer_id" - $ref: "#/components/parameters/page_size" - $ref: "#/components/parameters/page" - $ref: "#/components/parameters/total_required" - $ref: "#/components/parameters/content_type" security: - Oauth2: - https://uri.paypal.com/services/vault/payment-tokens/readwrite tags: - payment-tokens /v3/vault/payment-tokens/{id}: get: description: Returns a readable representation of vaulted payment source associated with the payment token id. summary: Retrieve a payment token operationId: payment-tokens.get responses: "200": description: Successful execution. content: application/json: schema: $ref: "#/components/schemas/payment_token_response" "403": description: Authorization failed due to insufficient permissions. content: application/json: schema: $ref: "#/components/schemas/error" "404": description: The specified resource does not exist. content: application/json: schema: $ref: "#/components/schemas/error" "422": description: The requested action could not be performed, semantically incorrect, or failed business validation. content: application/json: schema: $ref: "#/components/schemas/error" "500": description: An internal server error has occurred. content: application/json: schema: $ref: "#/components/schemas/error" parameters: - $ref: "#/components/parameters/id" - $ref: "#/components/parameters/content_type" security: - Oauth2: - https://uri.paypal.com/services/vault/payment-tokens/readwrite tags: - payment-tokens delete: description: Delete the payment token associated with the payment token id. summary: Delete payment token operationId: payment-tokens.delete responses: "204": description: The server has successfully executed the method, but there is no entity body to return. "400": description: Request is not well-formed, syntactically incorrect, or violates schema. content: application/json: schema: $ref: "#/components/schemas/error" "403": description: Authorization failed due to insufficient permissions. content: application/json: schema: $ref: "#/components/schemas/error" "500": description: An internal server error has occurred. content: application/json: schema: $ref: "#/components/schemas/error" parameters: - $ref: "#/components/parameters/id" - $ref: "#/components/parameters/content_type" security: - Oauth2: - https://uri.paypal.com/services/vault/payment-tokens/readwrite tags: - payment-tokens /v3/vault/setup-tokens: post: description: Creates a Setup Token from the given payment source and adds it to the Vault of the associated customer. summary: Create a setup token operationId: setup-tokens.create responses: "200": description: Idempotent response for a successful creation of setup token. content: application/json: schema: $ref: "#/components/schemas/setup_token_response" "201": description: A successful creation of setup token. content: application/json: schema: $ref: "#/components/schemas/setup_token_response" "400": description: Request is not well-formed, syntactically incorrect, or violates schema. content: application/json: schema: $ref: "#/components/schemas/error" "403": description: Authorization failed due to insufficient permissions. content: application/json: schema: $ref: "#/components/schemas/error" "422": description: The requested action could not be performed, semantically incorrect, or failed business validation. content: application/json: schema: $ref: "#/components/schemas/error" "500": description: An internal server error has occurred. content: application/json: schema: $ref: "#/components/schemas/error" parameters: - $ref: "#/components/parameters/content_type" - $ref: "#/components/parameters/paypal_request_id" requestBody: content: application/json: schema: $ref: "#/components/schemas/setup_token_request" description: Setup Token creation with a instrument type optional financial instrument details and customer_id. required: true security: - Oauth2: - https://uri.paypal.com/services/vault/payment-tokens/read tags: - setup-tokens /v3/vault/setup-tokens/{id}: get: description: Returns a readable representation of temporarily vaulted payment source associated with the setup token id. summary: Retrieve a setup token operationId: setup-tokens.get responses: "200": description: Found requested setup-token, returned a payment method associated with the token. content: application/json: schema: $ref: "#/components/schemas/setup_token_response" "403": description: Authorization failed due to insufficient permissions. content: application/json: schema: $ref: "#/components/schemas/error" "404": description: The specified resource does not exist. content: application/json: schema: $ref: "#/components/schemas/error" "422": description: The requested action could not be performed, semantically incorrect, or failed business validation. content: application/json: schema: $ref: "#/components/schemas/error" "500": description: An internal server error has occurred. content: application/json: schema: $ref: "#/components/schemas/error" parameters: - $ref: "#/components/parameters/id" - $ref: "#/components/parameters/content_type" security: - Oauth2: - https://uri.paypal.com/services/vault/payment-tokens/read tags: - setup-tokens tags: - name: payment-tokens description: Use the `/vault/payment-tokens` resource to create, retrieve, and delete a payment token that may optionally be associated with a customer. - name: setup-tokens description: Use the `/vault/setup-tokens` resource to create and retrieve temporary vault payment methods. - name: tokens description: Use the `/vault/tokens` resource to detokenize a vault token to retrieve details associated to the underlying payment source. - name: tokens-session description: Use the `/vault/tokens/{id}/session` resource to read the token session cache and retrieve details associated to the underlying payment source. - name: customers description: Use the `/vault/customers` resource to create, update, get and delete a customer. - name: payment-method-credentials description: Use the `/vault/payment-method-credentials` resource to create payment method credentials externalDocs: url: https://developer.paypal.com/docs/api/vault/v3/ servers: - url: https://api-m.sandbox.paypal.com description: PayPal API Sandbox components: securitySchemes: Oauth2: type: oauth2 description: Oauth 2.0 authentication flows: clientCredentials: tokenUrl: /api/oauth-proxy scopes: https://uri.paypal.com/services/vault/payment-tokens/readwrite: Manage payment instruments https://uri.paypal.com/services/vault/payment-tokens/read: Permission to only read from vault https://uri.paypal.com/services/vault/customers/read: Permission to read customer information. https://uri.paypal.com/services/vault/customers/readwrite: Permission to create/update customer information. https://uri.paypal.com/services/vault/payment-credentials/readwrite: Permission to access payment credentials. responses: default: description: The default response. content: application/json: schema: $ref: "#/components/schemas/error_default" schemas: 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}$ ach_debit_request: properties: verification_intent: description: The API caller can specify the verification intent when vaulting ACH. $ref: "#/components/schemas/ach_verification_intent" verification: description: The API caller can specify the verification method when vaulting ACH. $ref: "#/components/schemas/ach_debit_verification" title: ACH Debit Request description: A Resource representing a request to vault a ACH Debit. ach_debit_verification: {} ach_verification_intent: {} 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" apple_pay_payment_token_response: type: object title: Apple Pay Response description: A resource representing a response for Apple Pay. properties: card: type: object title: Apple Pay Card description: The payment card to be used to fund a payment. 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: description: The payment card type. $ref: "#/components/schemas/card_type" brand: description: The card brand or network. Typically used in the response. $ref: "#/components/schemas/card_brand" billing_address: description: "The portable international postal address. Maps to [AddressValidationMetadata](https://github.com/googlei18n/libad\ dressinput/wiki/AddressValidationMetadata) and HTML 5.1 [Autofilling form controls: the autocomplete attribute](https://www.w3.org/TR/html51/sec-forms.html#autofill\ ing-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 apple_pay_request: type: object title: Apple Pay Request description: A resource representing a request to vault Apple Pay. properties: token: description: Encrypted Apple Pay token, containing card information. This token would be base64 encoded. type: string minLength: 1 maxLength: 10000 pattern: ^.*$ card: type: object title: Apple Pay Card description: The payment card to be used to fund a payment. Can be a credit or debit card. properties: type: description: The payment card type. $ref: "#/components/schemas/card_type" brand: description: The card brand or network. Typically used in the response. $ref: "#/components/schemas/card_brand" billing_address: description: "The portable international postal address. Maps to [AddressValidationMetadata](https://github.com/googlei18n/libad\ dressinput/wiki/AddressValidationMetadata) and HTML 5.1 [Autofilling form controls: the autocomplete attribute](https://www.w3.org/TR/html51/sec-forms.html#autofill\ ing-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 bank_request: title: Bank Request description: A Resource representing a request to vault a Bank used for ACH Debit. type: object properties: ach_debit: description: ACH Debit Instrument Details to be vaulted as the payment method. $ref: "#/components/schemas/ach_debit_request" sepa_debit: description: SEPA Debit Instrument Details to be vaulted as the payment method. $ref: "#/components/schemas/sepa_debit_request" 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_]+$ enum: - REGULAR - TRIAL oneOf: - type: string enum: - REGULAR description: A regular billing cycle to identify recurring charges for the billing agreement. - type: string enum: - 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. pricing_scheme: description: The active pricing scheme for this billing cycle. A free trial billing cycle does not require a pricing scheme. $ref: "#/components/schemas/pricing_scheme" frequency: description: The frequency details for this billing cycle. $ref: "#/components/schemas/frequency" 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: 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. $ref: "#/components/schemas/date_no_time" required: - tenure_type 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" 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: description: The [two-character ISO-3166-1 country code](/docs/integration/direct/rest/country-codes/) of the bank. $ref: "#/components/schemas/country_code-2" products: $ref: "#/components/schemas/products_list" 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_]+$ 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 oneOf: - type: string enum: - VISA description: Visa card. - type: string enum: - MASTERCARD description: Mastercard card. - type: string enum: - DISCOVER description: Discover card. - type: string enum: - AMEX description: American Express card. - type: string enum: - SOLO description: Solo debit card. - type: string enum: - JCB description: Japan Credit Bureau card. - type: string enum: - STAR description: Military Star card. - type: string enum: - DELTA description: Delta Airlines card. - type: string enum: - SWITCH description: Switch credit card. - type: string enum: - MAESTRO description: Maestro credit card. - type: string enum: - CB_NATIONALE description: Carte Bancaire (CB) credit card. - type: string enum: - CONFIGOGA description: Configoga credit card. - type: string enum: - CONFIDIS description: Confidis credit card. - type: string enum: - ELECTRON description: Visa Electron credit card. - type: string enum: - CETELEM description: Cetelem credit card. - type: string enum: - CHINA_UNION_PAY description: China union pay credit card. - type: string enum: - 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. - type: string enum: - ELO description: The Brazilian Elo card payment network. - type: string enum: - HIPER description: The Hiper - Ingenico ePayment network. - type: string enum: - HIPERCARD description: The Brazilian Hipercard payment network that's widely accepted in the retail market. - type: string enum: - RUPAY description: The RuPay payment network. - type: string enum: - GE description: The GE Credit Union 3Point card payment network. - type: string enum: - SYNCHRONY description: The Synchrony Financial (SYF) payment network. - type: string enum: - EFTPOS description: The Electronic Fund Transfer At Point of Sale(EFTPOS) Debit card payment network. - type: string enum: - CARTE_BANCAIRE description: The Carte Bancaire payment network. - type: string enum: - STAR_ACCESS description: The Star Access payment network. - type: string enum: - PULSE description: The Pulse payment network. - type: string enum: - NYCE description: The NYCE payment network. - type: string enum: - ACCEL description: The Accel payment network. - type: string enum: - UNKNOWN description: UNKNOWN payment network. card_experience_context: type: object title: Card Experience Context description: A resource representing an experience context of vault a card. 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: description: The BCP 47-formatted locale of pages that the PayPal vaulting 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`. $ref: "#/components/schemas/language" return_url: type: string format: uri minLength: 1 maxLength: 4000 description: The URL where the customer is redirected after customer approves leaves the flow. It is a required field for contingency flows like PayPal wallet, 3DS. cancel_url: type: string format: uri minLength: 1 maxLength: 4000 description: The URL where the customer is redirected after customer cancels or leaves the flow. It is a required field for contingency flows like PayPal wallet, 3DS. vault_instruction: description: DEPRECATED. Vault Instruction on action to be performed after a successful payer approval. $ref: "#/components/schemas/vault_instruction" deprecated: true user_action: description: User Action on action to be performed after a successful payer approval. $ref: "#/components/schemas/user_action" card_response: type: object title: Card Response description: Full representation of a Card Payment Token including network token. allOf: - $ref: "#/components/schemas/card_response_entity" - properties: network_token: $ref: "#/components/schemas/network_token_entity" card_response_entity: type: object title: Card Response Entity description: Full representation of a Card Payment Token. properties: name: type: string description: The card holder's name as it appears on the card. minLength: 2 maxLength: 300 pattern: ^[A-Za-z ]+$ last_digits: type: string description: The last digits of the payment card. pattern: "[0-9]{2,}" minLength: 2 maxLength: 4 readOnly: true brand: description: The card brand or network. Typically used in the response. readOnly: true $ref: "#/components/schemas/card_brand" expiry: description: The card expiration year and month, in [Internet date format](https://tools.ietf.org/html/rfc3339#section-5.6). $ref: "#/components/schemas/date_year_month" billing_address: type: object title: Address request details. description: Address request details. 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" id: type: string description: The resource ID of the address. minLength: 1 maxLength: 36 pattern: ^[0-9A-Za-z-_]+$ required: - country_code verification_status: description: Card Verification status. $ref: "#/components/schemas/card_verification_status" verification: $ref: "#/components/schemas/card_verification_details" network_transaction_reference: $ref: "#/components/schemas/network_transaction_reference_response" authentication_result: type: object title: Authentication Response description: Results of Authentication such as 3D Secure. properties: three_d_secure: $ref: "#/components/schemas/three_d_secure_authentication_response-2" bin_details: description: Bank Identification Number (BIN) details used to fund a payment. $ref: "#/components/schemas/bin_details" type: description: The payment card type. $ref: "#/components/schemas/card_type" 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_]+$ enum: - CREDIT - DEBIT - PREPAID - STORE - UNKNOWN oneOf: - type: string enum: - CREDIT description: A credit card. - type: string enum: - DEBIT description: A debit card. - type: string enum: - PREPAID description: A Prepaid card. - type: string enum: - STORE description: A store card. - type: string enum: - UNKNOWN description: Card type cannot be determined. card_verification_details: title: Card Verification Details type: object description: Card Verification details including the authorization details and 3D SECURE details. properties: network_transaction_id: description: DEPRECATED. This field is DEPRECATED. Please find the network transaction id data in the 'id' field under the 'network_transaction_reference' object instead of the 'verification' object. type: string minLength: 1 maxLength: 1024 pattern: ^[a-zA-Z0-9-_@.:&+=*^'~#!$%()]+$ deprecated: true date: type: string minLength: 4 maxLength: 4 pattern: ^[0-9]+$ description: DEPRECATED. This field is DEPRECATED. Please find the date data in the 'date' field under the 'network_transaction_reference' object instead of the 'verification' object. deprecated: true network: description: DEPRECATED. This field is DEPRECATED. Please find the network data in the 'network' field under the 'network_transaction_reference' object instead of the 'verification' object. $ref: "#/components/schemas/card_brand" deprecated: true time: description: DEPRECATED. This field is DEPRECATED. Please find the time data in the 'time' field under the 'network_transaction_reference' object instead of the 'verification' object. readOnly: true $ref: "#/components/schemas/date_time" deprecated: true amount: description: The amount used for card verification. $ref: "#/components/schemas/money" processor_response: description: The processor response information for payment requests, such as direct credit card transactions. type: object title: Processor Response properties: avs_code: description: The address verification code for Visa, Discover, Mastercard, or American Express transactions. type: string readOnly: true 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" oneOf: - type: string enum: - 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. - type: string enum: - B description: For Visa, Mastercard, or Discover transactions, the address matches. International A. - type: string enum: - C description: For Visa, Mastercard, or Discover transactions, no values match. International N. - type: string enum: - D description: For Visa, Mastercard, or Discover transactions, the address and postal code match. International X. - type: string enum: - 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. - type: string enum: - 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. - type: string enum: - G description: For Visa, Mastercard, or Discover transactions, global is unavailable. Nothing matches. - type: string enum: - I description: For Visa, Mastercard, or Discover transactions, international is unavailable. Not applicable. - type: string enum: - 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. - type: string enum: - N description: For Visa, Mastercard, or Discover transactions, nothing matches. For American Express card holder, the address and postal code are both incorrect. - type: string enum: - P description: For Visa, Mastercard, or Discover transactions, postal international Z. Postal code only. - type: string enum: - R description: For Visa, Mastercard, or Discover transactions, re-try the request. For American Express, the system is unavailable. - type: string enum: - S description: For Visa, Mastercard, Discover, or American Express, the service is not supported. - type: string enum: - 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. - type: string enum: - 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. - type: string enum: - 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. - type: string enum: - 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. - type: string enum: - 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. - type: string enum: - "Null" description: For Maestro, no AVS response was obtained. - type: string enum: - "0" description: For Maestro, all address information matches. - type: string enum: - "1" description: For Maestro, none of the address information matches. - type: string enum: - "2" description: For Maestro, part of the address information matches. - type: string enum: - "3" description: For Maestro, the merchant did not provide AVS information. It was not processed. - type: string enum: - "4" description: For Maestro, the address was not checked or the acquirer had no response. The service is not available. cvv_code: description: The card verification value code for for Visa, Discover, Mastercard, or American Express. type: string readOnly: true enum: - E - I - M - N - P - S - U - X - All others - "0" - "1" - "2" - "3" - "4" oneOf: - type: string enum: - E description: For Visa, Mastercard, Discover, or American Express, error - unrecognized or unknown response. - type: string enum: - I description: For Visa, Mastercard, Discover, or American Express, invalid or null. - type: string enum: - M description: For Visa, Mastercard, Discover, or American Express, the CVV2/CSC matches. - type: string enum: - N description: For Visa, Mastercard, Discover, or American Express, the CVV2/CSC does not match. - type: string enum: - P description: For Visa, Mastercard, Discover, or American Express, it was not processed. - type: string enum: - S description: For Visa, Mastercard, Discover, or American Express, the service is not supported. - type: string enum: - U description: For Visa, Mastercard, Discover, or American Express, unknown - the issuer is not certified. - type: string enum: - X description: For Visa, Mastercard, Discover, or American Express, no response. For Maestro, the service is not available. - type: string enum: - All others description: For Visa, Mastercard, Discover, or American Express, error. - type: string enum: - "0" description: For Maestro, the CVV2 matched. - type: string enum: - "1" description: For Maestro, the CVV2 did not match. - type: string enum: - "2" description: For Maestro, the merchant has not implemented CVV2 code handling. - type: string enum: - "3" description: For Maestro, the merchant has indicated that CVV2 is not present on card. - type: string enum: - "4" description: For Maestro, the service is not available. three_d_secure: description: DEPRECATED. This field is DEPRECATED. Please find the 3D secure authentication data in the 'three_d_secure' object under the 'authentication_result' object instead of the 'verification' object. deprecated: true card_verification_method: title: Card Verification Method type: string description: The verification method of the card. minLength: 1 maxLength: 255 pattern: ^[0-9A-Z_]+$ enum: - SCA_WHEN_REQUIRED - SCA_ALWAYS oneOf: - type: string enum: - SCA_WHEN_REQUIRED description: 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. - type: string enum: - 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. card_verification_status: title: Card Verification Status type: string minLength: 1 maxLength: 255 pattern: ^[0-9A-Z_]+$ description: Verification status of Card. enum: - VERIFIED - FAILED oneOf: - type: string enum: - VERIFIED description: "Card has been verified " - type: string enum: - FAILED description: "Card verification has failed " 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)$ 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)$ currency_code: description: The [three-character ISO-4217 currency code](/api/rest/reference/currency-codes/) that identifies the currency. type: string minLength: 3 maxLength: 3 x-security-classification: data_class: class4 data_category: INTRINSIC customer: type: object title: Customer Request description: This object defines a customer in your system. Use it to manage customer profiles, save payment methods and contact details. properties: id: description: The unique ID for a customer in merchant's or partner's system of records. $ref: "#/components/schemas/merchant_partner_customer_id" merchant_customer_id: type: string 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. minLength: 1 maxLength: 64 pattern: ^[0-9a-zA-Z-_.^*$@#]+$ customer_vault_payment_tokens_response: title: Vault of a customer description: Collection of payment tokens saved for a given customer. properties: total_items: type: integer description: Total number of items. minimum: 1 maximum: 50 total_pages: type: integer description: Total number of pages. minimum: 1 maximum: 10 customer: type: object title: Customer Request description: This object defines a customer in your system. Use it to manage customer profiles, save payment methods and contact details. properties: id: description: The unique ID for a customer in merchant's or partner's system of records. $ref: "#/components/schemas/merchant_partner_customer_id" merchant_customer_id: type: string 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. minLength: 1 maxLength: 64 pattern: ^[0-9a-zA-Z-_.^*$@#]+$ payment_tokens: $ref: "#/components/schemas/payment_token_response_list" links: $ref: "#/components/schemas/link_description_list" 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])$ 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})$ 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])$ definitions-link_description_list: type: array description: An array of request-related [HATEOAS links](/api/rest/responses/#hateoas-links) that are either relevant to the issue by providing additional information or offering potential resolutions. readOnly: true minItems: 1 maxItems: 4 items: $ref: "#/components/schemas/link_description" definitions-payment_source: title: Payment source request description: The payment method to vault with the instrument details. type: object properties: card: type: object title: Card Request description: A Resource representing a request to vault a 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: description: "The card expiration year and month, in [Internet date format](https://tools.ietf.org/html/rfc3339#section-5.6) For example: 2028-04" $ref: "#/components/schemas/date_year_month" 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 brand: description: The card brand or network. Typically used in the response. $ref: "#/components/schemas/card_brand" billing_address: description: "The portable international postal address. Maps to [AddressValidationMetadata](https://github.com/googlei18n/libad\ dressinput/wiki/AddressValidationMetadata) and HTML 5.1 [Autofilling form controls: the autocomplete attribute](https://www.w3.org/TR/html51/sec-forms.html#autofill\ ing-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 network_transaction_reference: $ref: "#/components/schemas/network_transaction_reference_request" token: $ref: "#/components/schemas/token_id_request" 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])+)\]) 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])+)\])$ enrolled: type: string minLength: 1 maxLength: 255 pattern: ^[0-9A-Z_]+$ description: Status of Authentication eligibility. enum: - Y - N - U - B oneOf: - type: string enum: - Y description: Yes. The bank is participating in 3-D Secure protocol and will return the ACSUrl. - type: string enum: - N description: No. The bank is not participating in 3-D Secure protocol. - type: string enum: - U description: Unavailable. The DS or ACS is not available for authentication at the time of the request. - type: string enum: - B description: Bypass. The merchant authentication rule is triggered to bypass authentication. error: type: object title: Error description: The error details. properties: name: type: string description: The human-readable, unique name of the error. message: type: string description: The message that describes the error. debug_id: type: string description: The PayPal internal ID. Used for correlation purposes. details: $ref: "#/components/schemas/error_details_list" links: $ref: "#/components/schemas/error_definitions-link_description_list" required: - name - message - debug_id 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" 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" 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_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_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" 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" examples: - 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 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" examples: - name: SERVICE_UNAVAILABLE message: Service Unavailable. debug_id: 90957fca61718 information_link: https://developer.paypal.com/docs/api/orders/v2/#error-SERVICE_UNAVAILABLE 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_500" - $ref: "#/components/schemas/error_503" error_definitions-link_description_list: type: array description: An array of request-related [HATEOAS links](/api/rest/responses/#hateoas-links). readOnly: true 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_details-2: 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: type: string description: The location of the field that caused the error. Value is `body`, `path`, or `query`. default: body issue: type: string description: The unique, fine-grained application-level error code. links: $ref: "#/components/schemas/definitions-link_description_list" 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_details_list: type: array description: An array of additional details about the error. items: $ref: "#/components/schemas/error_details-2" 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_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 experience_context: type: object title: Experience Context description: Customizes the Vault creation flow experience for your customers. 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: description: The BCP 47-formatted locale of pages that the PayPal vaulting 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`. $ref: "#/components/schemas/language" return_url: type: string format: uri minLength: 1 maxLength: 4000 description: The URL where the customer is redirected after customer approves leaves the flow. It is a required field for contingency flows like PayPal wallet, 3DS. cancel_url: type: string format: uri minLength: 1 maxLength: 4000 description: The URL where the customer is redirected after customer cancels or leaves the flow. It is a required field for contingency flows like PayPal wallet, 3DS. shipping_preference: type: string description: The shipping preference. This only applies to PayPal payment source. default: GET_FROM_FILE minLength: 1 maxLength: 255 pattern: ^[0-9A-Z_]+$ enum: - GET_FROM_FILE - NO_SHIPPING - SET_PROVIDED_ADDRESS oneOf: - type: string enum: - GET_FROM_FILE description: Use the payer-provided shipping address on the PayPal site. - type: string enum: - NO_SHIPPING description: Redact the shipping address from the PayPal site. Recommended for digital goods. - type: string enum: - SET_PROVIDED_ADDRESS description: Use the merchant/platform-provided address. The payer cannot change this address on the PayPal site. If the merchant does not pass an address, the customer can choose the address on the PayPal site. vault_instruction: description: DEPRECATED. Vault Instruction on action to be performed after a successful payer approval. $ref: "#/components/schemas/vault_instruction" deprecated: true app_switch_context: $ref: "#/components/schemas/app_switch_context" user_action: description: User Action on action to be performed after a successful payer approval. $ref: "#/components/schemas/user_action" frequency: {} 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}))?$ 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 oneOf: - type: string enum: - GET description: The HTTP GET method. - type: string enum: - POST description: The HTTP POST method. - type: string enum: - PUT description: The HTTP PUT method. - type: string enum: - DELETE description: The HTTP DELETE method. - type: string enum: - HEAD description: The HTTP HEAD method. - type: string enum: - CONNECT description: The HTTP CONNECT method. - type: string enum: - OPTIONS description: The HTTP OPTIONS method. - type: string enum: - PATCH description: The HTTP PATCH method. link_description_list: description: An array of related [HATEOAS links](/api/rest/responses/#hateoas). readOnly: true type: array minItems: 1 maxItems: 32 items: $ref: "#/components/schemas/link_description" 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_-]+$ 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 enum: - AUTO - MANUAL oneOf: - type: string enum: - AUTO description: After payment approval in the PayPal App, buyer will automatically be redirected to the merchant website. - type: string enum: - 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. 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: ^.*$ 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 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_]+$ enum: - ANDROID - IOS - OTHER oneOf: - type: string enum: - ANDROID description: Google Android OS. - type: string enum: - IOS description: Apple OS typically found in Apple mobile devices. - type: string enum: - OTHER description: Any other OS type. os_version: type: string readOnly: true description: Operating System version of the device that the buyer is using. minLength: 1 maxLength: 64 pattern: ^.*$ network_token_entity: {} 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. network: description: Name of the card network through which the transaction was routed. $ref: "#/components/schemas/card_brand" 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]+$ network_transaction_reference_entity: allOf: - $ref: "#/components/schemas/network_transaction" - type: object title: Network Transaction Reference description: Reference values used by the card network to identify a transaction. required: - id - properties: time: description: The date and time when the instrument was verified. readOnly: true $ref: "#/components/schemas/date_time" - title: Network Transaction Reference Entity type: object description: Previous network transaction reference including id and network. network_transaction_reference_request: {} network_transaction_reference_response: title: Network Transaction Reference Response type: object description: Previous network transaction reference including id in response. allOf: - $ref: "#/components/schemas/network_transaction_reference_entity" one_time_charges: title: One-Time Charges Info description: The one-time charge info at the time of checkout. type: object properties: setup_fee: description: The setup fee for the recurring plan. $ref: "#/components/schemas/money" shipping_amount: description: The shipping amount due at the time of checkout. $ref: "#/components/schemas/money" taxes: description: The taxes due at the time of checkout. $ref: "#/components/schemas/money" product_price: description: The product price for any one-time product purchased at the time of checkout. $ref: "#/components/schemas/money" subtotal: description: The subtotal at the time of checkout. This is calculated by using the formula x + y + z where x is first-recurring-charge, y is setup-fee and z is item-price. readOnly: true $ref: "#/components/schemas/money" total_amount: description: The total amount at the time of checkout. This is calculated by using the formula x + y + z where x is subtotal, y is shipping-amount and z is taxes. $ref: "#/components/schemas/money" required: - total_amount pares_status: type: string minLength: 1 maxLength: 255 pattern: ^[0-9A-Z_]+$ description: Transactions status result identifier. The outcome of the issuer's authentication. enum: - Y - N - U - A - C - R - D - I oneOf: - type: string enum: - Y description: Successful authentication. - type: string enum: - N description: Failed authentication / account not verified / transaction denied. - type: string enum: - U description: Unable to complete authentication. - type: string enum: - A description: Successful attempts transaction. - type: string enum: - C description: Challenge required for authentication. - type: string enum: - R description: Authentication rejected (merchant must not submit for authorization). - type: string enum: - D description: Challenge required; decoupled authentication confirmed. - type: string enum: - I description: Informational only; 3DS requestor challenge preference acknowledged. 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: description: The email address of the payer. $ref: "#/components/schemas/email" payer_id: description: The PayPal-assigned ID for the payer. readOnly: true $ref: "#/components/schemas/account_id" payment_source: title: Payment token response payment source description: The vaulted payment method details. type: object properties: card: $ref: "#/components/schemas/card_response" paypal: $ref: "#/components/schemas/paypal_wallet_response" venmo: $ref: "#/components/schemas/venmo_response" apple_pay: $ref: "#/components/schemas/apple_pay_payment_token_response" payment_token_request: title: Payment Token Request description: Payment Token Request where the `source` defines the type of instrument to be stored. type: object properties: customer: description: This object defines a customer in your system. Use it to manage customer profiles, save payment methods and contact details. type: object title: Customer Request properties: id: description: The unique ID for a customer in merchant's or partner's system of records. $ref: "#/components/schemas/merchant_partner_customer_id" merchant_customer_id: type: string 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. minLength: 1 maxLength: 64 pattern: ^[0-9a-zA-Z-_.^*$@#]+$ payment_source: $ref: "#/components/schemas/definitions-payment_source" required: - payment_source payment_token_response: title: Payment Token Response description: Full representation of a saved payment token. type: object properties: id: description: The PayPal-generated ID for the vault token. $ref: "#/components/schemas/vault_id" customer: description: Customer in merchant's or partner's system of records. $ref: "#/components/schemas/customer" payment_source: $ref: "#/components/schemas/payment_source" links: $ref: "#/components/schemas/link_description_list" payment_token_response_list: type: array minItems: 0 maxItems: 64 items: $ref: "#/components/schemas/payment_token_response" payment_token_status: title: Payment Token Status type: string description: The status of the payment token. minLength: 1 maxLength: 255 pattern: ^[0-9A-Z_]+$ default: CREATED enum: - CREATED - PAYER_ACTION_REQUIRED - APPROVED - VAULTED - TOKENIZED oneOf: - type: string enum: - CREATED description: A setup token is initialized with minimal information, more data must be added to the setup-token to be vaulted - type: string enum: - PAYER_ACTION_REQUIRED description: A contingency on payer approval is required before the payment method can be saved. - type: string enum: - APPROVED description: Setup token is ready to be vaulted. If a buyer approval contigency was returned, it is has been approved. - type: string enum: - VAULTED description: The payment token has been vaulted. - type: string enum: - TOKENIZED description: A vaulted payment method token has been tokenized for short term (one time) use. paypal_wallet_experience_context: type: object title: PayPal Wallet Experience Context description: A resource representing an experience context of vault PayPal Wallet. allOf: - $ref: "#/components/schemas/experience_context" - properties: {} paypal_wallet_request: type: object title: PayPal Wallet Request description: A resource representing a request to vault PayPal Wallet. allOf: - $ref: "#/components/schemas/wallet_base" - properties: billing_plan: $ref: "#/components/schemas/plan" experience_context: $ref: "#/components/schemas/paypal_wallet_experience_context" paypal_wallet_response: allOf: - description: Resource consolidating common request and response attributes for vaulting a Digital Wallet. $ref: "#/components/schemas/wallet_base" - description: Resource consolidating common request and response attributes for vaulting a Digital Wallet. - description: Resource consolidating common request and response attributes for vaulting a Digital Wallet. - $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: 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`. $ref: "#/components/schemas/phone_with_type" address: description: "The portable international postal address. Maps to [AddressValidationMetadata](https://github.com/googlei18n/libad\ dressinput/wiki/AddressValidationMetadata) and HTML 5.1 [Autofilling form controls: the autocomplete attribute](https://www.w3.org/TR/html51/sec-forms.html#autofill\ ing-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 - readOnly: true 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 - properties: account_id: readOnly: true description: The account identifier for a PayPal account. $ref: "#/components/schemas/account_id" phone_number: readOnly: true description: The phone number, in its canonical international [E.164 numbering plan format](https://www.itu.int/rec/T-REC-E.164/en). $ref: "#/components/schemas/phone" - title: PayPal Wallet Response description: Full representation of a PayPal Payment Token. type: object phone: type: object title: Phone description: The phone number, in its canonical international [E.164 numbering plan format](https://www.itu.int/rec/T-REC-E.164/en). 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}?$ extension_number: type: string description: The extension number. minLength: 1 maxLength: 15 pattern: ^[0-9]{1,15}?$ required: - country_code - national_number phone_type: type: string title: Phone Type description: The phone type. enum: - FAX - HOME - MOBILE - OTHER - PAGER oneOf: - type: string enum: - FAX description: Fax number. - type: string enum: - HOME description: Home phone number. - type: string enum: - MOBILE description: Mobile phone number. - type: string enum: - OTHER description: Other phone number. - type: string enum: - PAGER description: Pager number. 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 plan: title: Plan description: The merchant level Recurring Billing plan metadata for the Billing Agreement. type: object properties: billing_cycles: $ref: "#/components/schemas/billing_cycle_list" product: description: Product details associated with any one-time product purchase. $ref: "#/components/schemas/product_override" one_time_charges: description: Price and currency for any one-time charges due at plan signup. $ref: "#/components/schemas/one_time_charges" name: type: string description: Name of the recurring plan. minLength: 1 maxLength: 127 pattern: ^[A-Za-z0-9() +',.:-]+$ required: - billing_cycles - one_time_charges pricing_scheme: title: Pricing Scheme description: The pricing scheme details. type: object properties: price: description: The price the customer will be charged based on the pricing model $ref: "#/components/schemas/money" pricing_model: type: string description: The pricing model for the billing cycle. minLength: 1 maxLength: 24 pattern: ^[A-Z_]+$ enum: - FIXED - VARIABLE - AUTO_RELOAD oneOf: - type: string enum: - FIXED description: A fixed pricing scheme where the customer is charged a fixed amount. - type: string enum: - VARIABLE description: A variable pricing scheme where the customer is charged a variable amount. - type: string enum: - AUTO_RELOAD description: A auto-reload pricing scheme where the customer is charged a fixed amount for reload. reload_threshold_amount: 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. $ref: "#/components/schemas/money" required: - pricing_model product_override: {} products: type: string description: This value provides the category of the BIN. minLength: 1 maxLength: 255 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 sepa_debit_experience_context: type: object title: SEPA Debit Experience Context description: Customizes the payer experience during the approval process for the SEPA Debit payment. properties: locale: 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`. $ref: "#/components/schemas/language" return_url: description: The URL where the customer is redirected after the customer approves the payment. format: uri $ref: "#/components/schemas/url" cancel_url: description: The URL where the customer is redirected after the customer cancels the payment. format: uri $ref: "#/components/schemas/url" required: - return_url - cancel_url sepa_debit_request: properties: mandate_intent: $ref: "#/components/schemas/sepa_mandate_intent" experience_context: description: Customizes the payer experience during the approval process for the payment. $ref: "#/components/schemas/sepa_debit_experience_context" title: SEPA Debit Request description: An API resource denoting a request to securely store a SEPA Debit. sepa_mandate_intent: {} setup_token_request: title: Setup Token description: Setup Token Request where the `source` defines the type of instrument to be stored. type: object properties: customer: description: This object defines a customer in your system. Use it to manage customer profiles, save payment methods and contact details. type: object title: Customer Request properties: id: description: The unique ID for a customer in merchant's or partner's system of records. $ref: "#/components/schemas/merchant_partner_customer_id" merchant_customer_id: type: string 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. minLength: 1 maxLength: 64 pattern: ^[0-9a-zA-Z-_.^*$@#]+$ payment_source: type: object description: The payment method to vault with the instrument details. properties: card: type: object title: Card Request description: A Resource representing a request to vault a 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: description: "The card expiration year and month, in [Internet date format](https://tools.ietf.org/html/rfc3339#section-5.6) For example: 2028-04" $ref: "#/components/schemas/date_year_month" 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 brand: description: The card brand or network. Typically used in the response. $ref: "#/components/schemas/card_brand" billing_address: description: "The portable international postal address. Maps to [AddressValidationMetadata](https://github.com/googlei18n/l\ ibaddressinput/wiki/AddressValidationMetadata) and HTML 5.1 [Autofilling form controls: the autocomplete attribute](https://www.w3.org/TR/html51/sec-forms.html#auto\ filling-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 verification_method: description: The API caller can opt in to verify the payment token through PayPal offered verification services (e.g. Smart Dollar Auth, 3DS). $ref: "#/components/schemas/card_verification_method" experience_context: $ref: "#/components/schemas/card_experience_context" network_transaction_reference: $ref: "#/components/schemas/network_transaction_reference_request" paypal: $ref: "#/components/schemas/paypal_wallet_request" venmo: $ref: "#/components/schemas/venmo_request" apple_pay: $ref: "#/components/schemas/apple_pay_request" token: $ref: "#/components/schemas/token_id_request" bank: $ref: "#/components/schemas/bank_request" shopper_session_id: description: Insights API's session identifier used to track the shopper's analytics. $ref: "#/components/schemas/shopper_session_id" required: - payment_source setup_token_response: title: Minimal Setup Token description: Minimal representation of a cached setup token. type: object properties: id: description: The PayPal-generated ID for the vault token. $ref: "#/components/schemas/vault_id" customer: description: This object defines a customer in your system. Use it to manage customer profiles, save payment methods and contact details. type: object title: Customer Request properties: id: description: The unique ID for a customer in merchant's or partner's system of records. $ref: "#/components/schemas/merchant_partner_customer_id" merchant_customer_id: type: string 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. minLength: 1 maxLength: 64 pattern: ^[0-9a-zA-Z-_.^*$@#]+$ status: description: The status of the payment token. $ref: "#/components/schemas/payment_token_status" payment_source: type: object description: The setup payment method details. properties: card: allOf: - $ref: "#/components/schemas/card_response_entity" - properties: {} - type: object title: Card Response description: Full representation of a Card Payment Token including network token. paypal: $ref: "#/components/schemas/paypal_wallet_response" venmo: $ref: "#/components/schemas/venmo_response" links: $ref: "#/components/schemas/link_description_list" shopper_session_id: {} three_d_secure_authentication_response: type: object title: Response of 3D Secure Authentication description: Results of 3D Secure Authentication. properties: authentication_status: description: The outcome of the issuer's authentication. $ref: "#/components/schemas/pares_status" enrollment_status: description: Status of authentication eligibility. $ref: "#/components/schemas/enrolled" three_d_secure_authentication_response-2: type: object title: Three D Secure Authentication Response description: Results of 3D Secure Authentication. allOf: - $ref: "#/components/schemas/three_d_secure_authentication_response" - properties: authentication_id: type: string description: The externally received 3ds authentication id, to be returned in card detokenization response. minLength: 1 maxLength: 255 pattern: ^[0-9a-zA-Z_-]+$ token_id_request: type: object title: Token Request description: The Tokenized Payment Source representing a Request to Vault a Token. properties: id: type: string description: The PayPal-generated ID for the token. minLength: 1 maxLength: 255 pattern: ^[0-9A-Za-z_-]+$ type: type: string description: The tokenization method that generated the ID. minLength: 1 maxLength: 255 pattern: ^[0-9A-Z_-]+$ enum: - SETUP_TOKEN oneOf: - type: string enum: - SETUP_TOKEN description: The setup token, which is a temporary reference to payment source. required: - id - type url: type: string description: Describes the URL. format: uri usage_pattern: title: Usage Pattern type: string description: Expected business/charge model for the billing agreement. minLength: 1 maxLength: 30 pattern: ^[0-9A-Z_]+$ enum: - IMMEDIATE - DEFERRED - RECURRING_PREPAID - RECURRING_POSTPAID - THRESHOLD_PREPAID - THRESHOLD_POSTPAID - UNSCHEDULED_POSTPAID - UNSCHEDULED_PREPAID - SUBSCRIPTION_PREPAID - SUBSCRIPTION_POSTPAID - INSTALLMENT_POSTPAID - INSTALLMENT_PREPAID oneOf: - type: string enum: - IMMEDIATE description: On-demand instant payments – non-recurring, pre-paid, variable amount, variable frequency. - type: string enum: - DEFERRED description: Pay after use, non-recurring post-paid, variable amount, irregular frequency. - type: string enum: - RECURRING_PREPAID description: Pay upfront fixed or variable amount on a fixed date before the goods/service is delivered. - type: string enum: - RECURRING_POSTPAID description: Pay on a fixed date based on usage or consumption after the goods/service is delivered. - type: string enum: - THRESHOLD_PREPAID description: Charge payer when the set amount is reached or monthly billing cycle, whichever comes first, before the goods/service is delivered. - type: string enum: - THRESHOLD_POSTPAID description: Charge payer when the set amount is reached or monthly billing cycle, whichever comes first, after the goods/service is delivered. - type: string enum: - UNSCHEDULED_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. - type: string enum: - 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. - type: string enum: - 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. - type: string enum: - 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. - type: string enum: - 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. - type: string enum: - 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. user_action: title: User Action type: string description: User Action on action to be performed after a successful payer approval. minLength: 1 maxLength: 255 pattern: ^[A-Z_]+$ default: CONTINUE enum: - SETUP_NOW - CONTINUE oneOf: - type: string enum: - SETUP_NOW description: After you redirect the customer to the PayPal payment page, a Setup Now button appears. Use this option when no additional inputs are needed from merchant site and to create the billing agreement immediately when the customer clicks Setup Now. - type: string enum: - CONTINUE description: After you redirect the customer to the PayPal payment page, a Continue button appears. Use this option when you want to redirect the customer from the completed payment page to the merchant site for additional inputs without immediately creating the billing agreement. 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_-]+$ vault_instruction: title: Vault Instruction type: string description: Vault Instruction on action to be performed after a successful payer approval. minLength: 1 maxLength: 255 pattern: ^[A-Z_]+$ default: ON_CREATE_PAYMENT_TOKENS enum: - ON_CREATE_PAYMENT_TOKENS - ON_PAYER_APPROVAL oneOf: - type: string enum: - ON_CREATE_PAYMENT_TOKENS description: Vault the payment method after API caller performs a successful POST on Payment Tokens. - type: string enum: - ON_PAYER_APPROVAL description: Vault the payment method on successful payer authentication and approval. venmo_experience_context: type: object title: Venmo Experience Context description: A resource representing an experience context of vault a venmo account. 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: ^.*$ shipping_preference: type: string description: The shipping preference. This only applies to PayPal payment source. default: GET_FROM_FILE minLength: 1 maxLength: 255 pattern: ^[0-9A-Z_]+$ enum: - GET_FROM_FILE - NO_SHIPPING - SET_PROVIDED_ADDRESS oneOf: - type: string enum: - GET_FROM_FILE description: Use the payer-provided shipping address on the PayPal site. - type: string enum: - NO_SHIPPING description: Redact the shipping address from the PayPal site. Recommended for digital goods. - type: string enum: - SET_PROVIDED_ADDRESS description: Use the merchant/platform-provided address. The payer cannot change this address on the PayPal site. If the merchant does not pass an address, the customer can choose the address on the PayPal site. vault_instruction: description: DEPRECATED. Vault Instruction on action to be performed after a successful payer approval. $ref: "#/components/schemas/vault_instruction" deprecated: true user_action: description: User Action on action to be performed after a successful payer approval. $ref: "#/components/schemas/user_action" venmo_request: type: object title: Venmo Request description: A resource representing a request to vault Venmo. allOf: - $ref: "#/components/schemas/wallet_base" - properties: experience_context: $ref: "#/components/schemas/venmo_experience_context" venmo_response: allOf: - description: Resource consolidating common request and response attributes for vaulting a Digital Wallet. $ref: "#/components/schemas/wallet_base" - description: Resource consolidating common request and response attributes for vaulting a Digital Wallet. - description: Resource consolidating common request and response attributes for vaulting a Digital Wallet. - $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: 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`. $ref: "#/components/schemas/phone_with_type" address: description: "The portable international postal address. Maps to [AddressValidationMetadata](https://github.com/googlei18n/libad\ dressinput/wiki/AddressValidationMetadata) and HTML 5.1 [Autofilling form controls: the autocomplete attribute](https://www.w3.org/TR/html51/sec-forms.html#autofill\ ing-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 - readOnly: true 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 - properties: user_name: description: The Venmo username, as chosen by the user. type: string pattern: ^[-a-zA-Z0-9_]*$ minLength: 1 maxLength: 50 - title: Venmo Response description: Full representation of a Venmo Payment Token. type: object wallet_base: type: object title: Vaulted Digital Wallet Common Attributes description: Resource consolidating common request and response attributes for vaulting a Digital Wallet. properties: description: type: string description: "The description displayed to the consumer on the approval flow for a digital wallet, as well as on the merchant view of the payment token management experience. exp: PayPal.com." minLength: 1 maxLength: 128 pattern: ^.*$ usage_pattern: description: Expected business/charge model for the billing agreement. $ref: "#/components/schemas/usage_pattern" shipping: description: The shipping details. type: object 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: description: The email address of the recipient of the shipped items, which may belong to either the payer, or an alternate contact, for delivery. $ref: "#/components/schemas/email_address" 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_]+$ enum: - SHIPPING - PICKUP_IN_PERSON - PICKUP_IN_STORE - PICKUP_FROM_PERSON oneOf: - type: string enum: - SHIPPING description: The payer intends to receive the items at a specified address. - type: string enum: - PICKUP_IN_PERSON description: DEPRECATED. Please use "PICKUP_FROM_PERSON" instead. - type: string enum: - 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. - type: string enum: - 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. address: description: "The portable international postal address. Maps to [AddressValidationMetadata](https://github.com/googlei18n/libad\ dressinput/wiki/AddressValidationMetadata) and HTML 5.1 [Autofilling form controls: the autocomplete attribute](https://www.w3.org/TR/html51/sec-forms.html#autofill\ ing-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 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 usage_type: type: string description: The usage type associated with a digital wallet payment token. minLength: 1 maxLength: 255 pattern: ^[0-9A-Z_]+$ enum: - MERCHANT - PLATFORM oneOf: - type: string enum: - MERCHANT description: The PayPal Payment Token will be used for future transaction directly with a merchant. - type: string enum: - 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. customer_type: type: string description: The customer type associated with a digital wallet 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_]+$ enum: - CONSUMER - BUSINESS oneOf: - type: string enum: - CONSUMER description: The customer vaulting the PayPal payment token is a consumer on the merchant / platform. - type: string enum: - BUSINESS description: The customer vaulting the PayPal payment token is a business on merchant / platform. parameters: content_type: name: Content-Type description: Specifies the request format. in: header required: false schema: type: string minLength: 1 maxLength: 255 pattern: ^[A-Za-z0-9/+-]+$ paypal_request_id: name: PayPal-Request-Id description: The server stores keys for 3 hours. in: header required: false schema: type: string minLength: 1 maxLength: 108 pattern: ^.*$ customer_id: name: customer_id description: A unique identifier representing a specific customer in merchant's/partner's system or records. in: query required: true schema: type: string minLength: 7 maxLength: 36 pattern: ^[0-9a-zA-Z_-]+$ page_size: name: page_size description: A non-negative, non-zero integer indicating the maximum number of results to return at one time. in: query required: false schema: type: integer minimum: 1 maximum: 5 default: 5 page: name: page description: A non-negative, non-zero integer representing the page of the results. in: query required: false schema: type: integer minimum: 1 maximum: 10 default: 1 total_required: name: total_required description: A boolean indicating total number of items (total_items) and pages (total_pages) are expected to be returned in the response. in: query required: false schema: type: boolean default: false id: name: id description: ID of the setup token. in: path required: true schema: type: string minLength: 7 maxLength: 36 pattern: ^[0-9a-zA-Z_-]+$ x-errors: - name: NOT_ENABLED_TO_VAULT_PAYMENT_SOURCE message: The API caller or the merchant on whose behalf the API call is initiated is not allowed to vault the given source. Please contact PayPal customer support for assistance. description: Authorization failed due to insufficient permissions. - name: PERMISSION_DENIED message: You do not have permission to access or perform operations on this resource. description: Authorization failed due to insufficient permissions. - name: PAYER_ACTION_REQUIRED message: Please make sure setup up token is approved. Please complete the approval flow [Payer Approval](/beta/vault/during-purchase/js-sdk/paypal/#link-payerapproval). description: The requested action could not be performed, semantically incorrect, or failed business validation. - name: PAYPAL_REQUEST_ID_PREVIOUSLY_USED message: The PayPal-Request-ID has already been used for another request. description: The requested action could not be performed, semantically incorrect, or failed business validation. - name: CARD_EXPIRATION_YEAR_IS_INVALID message: Expiration year outside of acceptable range. description: The requested action could not be performed, semantically incorrect, or failed business validation. - name: SETUP_TOKEN_ALREADY_TOKENIZED message: The setup token has been used previously to generate a payment token. description: The requested action could not be performed, semantically incorrect, or failed business validation. - name: SETUP_TOKEN_NOT_TOKENIZED message: The payment source represented by this setup token is not vaulted. description: The requested action could not be performed, semantically incorrect, or failed business validation. - name: INVALID_EXPIRY_DATE message: Expiry date is invalid. Expiry date should be a date in future and within the threshold for the payment source. description: The requested action could not be performed, semantically incorrect, or failed business validation. - name: OPERATION_NOT_SUPPORTED message: Specified operation not supported on any fields. description: The requested action could not be performed, semantically incorrect, or failed business validation. - name: INVALID_SECURITY_CODE message: The security code provided does not conform to the card number provided. description: The requested action could not be performed, semantically incorrect, or failed business validation. - name: CREDIT_CARD_NUMBER_IS_INVALID message: Credit card number is invalid. description: The request is not well-formed, is syntactically incorrect, or violates schema. - name: EXACTLY_ONE_FIELD_REQUIRED message: Exactly one payment source is required. description: The request is not well-formed, is syntactically incorrect, or violates schema. - name: INVALID_PARAMETER_SYNTAX message: The value of a field does not conform to the expected format. description: The request is not well-formed, is syntactically incorrect, or violates schema. - name: MISSING_REQUIRED_PARAMETER message: A required field / parameter is missing. description: The request is not well-formed, is syntactically incorrect, or violates schema. - name: INVALID_STRING_MAX_LENGTH message: The value of a field is too long. description: The request is not well-formed, is syntactically incorrect, or violates schema. - name: INVALID_STRING_LENGTH message: The value of a field is either too short or too long. description: The request is not well-formed, is syntactically incorrect, or violates schema. - name: MALFORMED_REQUEST_JSON message: The request JSON is not well formed. description: The request is not well-formed, is syntactically incorrect, or violates schema. - name: INVALID_INTEGER_MIN_VALUE message: The integer value of a field is too small. description: The request is not well-formed, is syntactically incorrect, or violates schema. - name: RESOURCE_NOT_FOUND message: The specified resource does not exist. description: The requested resource ID was not found - name: TOKEN_NOT_FOUND message: The specified token id does not exist. description: The requested resource ID was not found. - name: INTERNAL_SERVER_ERROR message: A system or application error occurred. Although the client appears to provide a correct request, something unexpected occurred on the server. description: An internal server error occurred.