> ## Documentation Index > Fetch the complete documentation index at: https://docs.paypal.ai/llms.txt > Use this file to discover all available pages before exploring further. # Create payment token for a given payment source > Creates a Payment Token from the given payment source and adds it to the Vault of the associated customer. ## OpenAPI ````yaml /api-reference/vault_payment_tokens_v3.json post /v3/vault/payment-tokens openapi: 3.0.3 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. version: '3.4' contact: {} servers: - url: https://api-m.sandbox.paypal.com description: PayPal Sandbox Environment - url: https://api-m.paypal.com description: PayPal Live Environment security: [] tags: - name: 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/ paths: /v3/vault/payment-tokens: post: tags: - payment-tokens summary: Create payment token for a given payment source description: >- Creates a Payment Token from the given payment source and adds it to the Vault of the associated customer. operationId: payment-tokens.create parameters: - $ref: '#/components/parameters/paypal_request_id' requestBody: content: application/json: schema: $ref: '#/components/schemas/payment_token_request' examples: payment_token_request: value: payment_source: token: id: 5C991763VB2781612 type: BILLING_AGREEMENT description: >- Payment Token creation with a financial instrument and an optional customer_id. required: true responses: '200': description: Idempotent response for a successful creation of payment token. content: application/json: schema: $ref: '#/components/schemas/payment_token_response' examples: payment_token_response: value: id: 8kk8451t customer: id: customer_4029352050 payment_source: card: last_digits: '1111' expiry: 2027-02 brand: VISA name: John Doe billing_address: address_line_1: 2211 N First Street address_line_2: 17.3.160 admin_area_2: San Jose admin_area_1: CA postal_code: '95131' country_code: US links: - rel: self href: >- https://api-m.paypal.com/v3/vault/payment-tokens/8kk8451t method: GET encType: application/json - rel: delete href: >- https://api-m.paypal.com/v3/vault/payment-tokens/8kk8451t method: DELETE encType: application/json '201': description: A successful creation of payment token. content: application/json: schema: $ref: '#/components/schemas/payment_token_response' examples: payment_token_response: value: id: 8kk8451t customer: id: customer_4029352050 payment_source: card: last_digits: '1111' expiry: 2027-02 brand: VISA name: John Doe billing_address: address_line_1: 2211 N First Street address_line_2: 17.3.160 admin_area_2: San Jose admin_area_1: CA postal_code: '95131' country_code: US links: - rel: self href: >- https://api-m.paypal.com/v3/vault/payment-tokens/8kk8451t method: GET encType: application/json - rel: delete href: >- https://api-m.paypal.com/v3/vault/payment-tokens/8kk8451t method: DELETE encType: application/json '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' security: - Oauth2: - https://uri.paypal.com/services/vault/payment-tokens/readwrite components: parameters: 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: 10000 pattern: ^.*$ schemas: '5': 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 '7': title: PayPal Wallet Response description: Full representation of a PayPal Payment Token. type: object 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: $ref: '#/components/schemas/customer' 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: $ref: '#/components/schemas/vault_id' description: The PayPal-generated ID for the vault token. customer: $ref: '#/components/schemas/customer' description: Customer in merchant's or partner's system of records. payment_source: $ref: '#/components/schemas/payment_source' links: $ref: '#/components/schemas/link_description_list' 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 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: $ref: '#/components/schemas/merchant_partner_customer_id' description: >- The unique ID for a customer in merchant's or partner's system of records. 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-_.^*$@#]+$ definitions-payment_source: title: Payment source request description: The payment method to vault with the instrument details. type: object properties: card: $ref: '#/components/schemas/payment_source_card' token: $ref: '#/components/schemas/token_id_request' vault_id: type: string description: The PayPal-generated ID for the vault token. minLength: 1 maxLength: 36 pattern: ^[0-9a-zA-Z_-]+$ 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' 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' error_details_list: type: array description: An array of additional details about the error. items: $ref: '#/components/schemas/error_details-2' 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' 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_-]+$ payment_source_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: $ref: '#/components/schemas/date_year_month' description: >- The card expiration year and month, in [Internet date format](https://tools.ietf.org/html/rfc3339#section-5.6). 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: $ref: '#/components/schemas/card_brand' description: The card brand or network. Typically used in the response. billing_address: $ref: '#/components/schemas/payment_source_card_billing_address' network_transaction_reference: $ref: '#/components/schemas/network_transaction_reference_request' 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_-]+$ x-enumDescriptions: - value: SETUP_TOKEN description: >- The setup token, which is a temporary reference to payment source. enum: - SETUP_TOKEN required: - id - type 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' paypal_wallet_response: allOf: - $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. - description: >- Resource consolidating common request and response attributes for vaulting a Digital Wallet. - $ref: '#/components/schemas/payer_base' - properties: name: $ref: '#/components/schemas/name' phone: $ref: '#/components/schemas/phone_with_type' description: >- The phone number of the customer. Available only when you enable the **Contact Telephone Number** option in the **Profile & Settings** for the merchant's PayPal account. The `phone.phone_number` supports only `national_number`. address: $ref: '#/components/schemas/address' - $ref: '#/components/schemas/5' - properties: account_id: $ref: '#/components/schemas/account_id' readOnly: true description: The account identifier for a PayPal account. phone_number: $ref: '#/components/schemas/phone' 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/7' venmo_response: allOf: - $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. - description: >- Resource consolidating common request and response attributes for vaulting a Digital Wallet. - $ref: '#/components/schemas/payer_base' - properties: name: $ref: '#/components/schemas/name' phone: $ref: '#/components/schemas/phone_with_type' description: >- The phone number of the customer. Available only when you enable the **Contact Telephone Number** option in the **Profile & Settings** for the merchant's PayPal account. The `phone.phone_number` supports only `national_number`. address: $ref: '#/components/schemas/address' - $ref: '#/components/schemas/5' - properties: user_name: description: The Venmo username, as chosen by the user. type: string pattern: ^[-a-zA-Z0-9_]*$ minLength: 1 maxLength: 50 - $ref: '#/components/schemas/definitions-7' apple_pay_payment_token_response: type: object title: Apple Pay Response description: A resource representing a response for Apple Pay. properties: card: $ref: '#/components/schemas/card' 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 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 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])$ card_brand: type: string title: Card Brand description: >- The card network or brand. Applies to credit, debit, gift, and payment cards. minLength: 1 maxLength: 255 pattern: ^[A-Z_]+$ x-enumDescriptions: - value: VISA description: Visa card. - value: MASTERCARD description: Mastecard card. - value: DISCOVER description: Discover card. - value: AMEX description: American Express card. - value: SOLO description: Solo debit card. - value: JCB description: Japan Credit Bureau card. - value: STAR description: Military Star card. - value: DELTA description: Delta Airlines card. - value: SWITCH description: Switch credit card. - value: MAESTRO description: Maestro credit card. - value: CB_NATIONALE description: Carte Bancaire (CB) credit card. - value: CONFIGOGA description: Configoga credit card. - value: CONFIDIS description: Confidis credit card. - value: ELECTRON description: Visa Electron credit card. - value: CETELEM description: Cetelem credit card. - value: CHINA_UNION_PAY description: China union pay credit card. - value: DINERS description: >- The Diners Club International banking and payment services capability network owned by Discover Financial Services (DFS), one of the most recognized brands in US financial services. - value: ELO description: The Brazilian Elo card payment network. - value: HIPER description: The Hiper - Ingenico ePayment network. - value: HIPERCARD description: >- The Brazilian Hipercard payment network that's widely accepted in the retail market. - value: RUPAY description: The RuPay payment network. - value: GE description: The GE Credit Union 3Point card payment network. - value: SYNCHRONY description: The Synchrony Financial (SYF) payment network. - value: EFTPOS description: >- The Electronic Fund Transfer At Point of Sale(EFTPOS) Debit card payment network. - value: UNKNOWN description: UNKNOWN payment network. enum: - VISA - MASTERCARD - DISCOVER - AMEX - SOLO - JCB - STAR - DELTA - SWITCH - MAESTRO - CB_NATIONALE - CONFIGOGA - CONFIDIS - ELECTRON - CETELEM - CHINA_UNION_PAY - DINERS - ELO - HIPER - HIPERCARD - RUPAY - GE - SYNCHRONY - EFTPOS - UNKNOWN payment_source_card_billing_address: description: >- The portable international postal address. Maps to [AddressValidationMetadata](https://github.com/googlei18n/libaddressinput/wiki/AddressValidationMetadata) and HTML 5.1 [Autofilling form controls: the autocomplete attribute](https://www.w3.org/TR/html51/sec-forms.html#autofilling-form-controls-the-autocomplete-attribute). type: object title: Portable Postal Address (Medium-Grained) properties: address_line_1: type: string description: >- The first line of the address, such as number and street, for example, `173 Drury Lane`. Needed for data entry, and Compliance and Risk checks. This field needs to pass the full address. maxLength: 300 address_line_2: type: string description: >- The second line of the address, for example, a suite or apartment number. maxLength: 300 admin_area_2: type: string description: A city, town, or village. Smaller than `admin_area_level_1`. maxLength: 120 admin_area_1: type: string description: >- The highest-level sub-division in a country, which is usually a province, state, or ISO-3166-2 subdivision. This data is formatted for postal delivery, for example, `CA` and not `California`. Value, by country, is: maxLength: 300 postal_code: type: string description: >- The postal code, which is the ZIP code or equivalent. Typically required for countries with a postal code or an equivalent. See [postal code](https://en.wikipedia.org/wiki/Postal_code). maxLength: 60 country_code: $ref: '#/components/schemas/country_code' required: - country_code network_transaction_reference_request: {} 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: $ref: '#/components/schemas/card_brand' description: The card brand or network. Typically used in the response. readOnly: true expiry: $ref: '#/components/schemas/date_year_month' description: >- The card expiration year and month, in [Internet date format](https://tools.ietf.org/html/rfc3339#section-5.6). billing_address: $ref: '#/components/schemas/billing_address' verification_status: $ref: '#/components/schemas/card_verification_status' description: Card Verification status. verification: $ref: '#/components/schemas/card_verification_details' network_transaction_reference: $ref: '#/components/schemas/network_transaction_reference_response' authentication_result: $ref: '#/components/schemas/authentication_result' bin_details: $ref: '#/components/schemas/bin_details' description: Bank Identification Number (BIN) details used to fund a payment. type: $ref: '#/components/schemas/card_type' description: The payment card type. network_token_entity: {} 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: type: string description: Expected business/charge model for the billing agreement. minLength: 1 maxLength: 30 pattern: ^[0-9A-Z_]+$ x-enumDescriptions: - value: IMMEDIATE description: >- On-demand instant payments – non-recurring, pre-paid, variable amount, variable frequency. - value: DEFERRED description: >- Pay after use, non-recurring post-paid, variable amount, irregular frequency. - value: RECURRING_PREPAID description: >- Pay upfront fixed or variable amount on a fixed date before the goods/service is delivered. - value: RECURRING_POSTPAID description: >- Pay on a fixed date based on usage or consumption after the goods/service is delivered. - value: THRESHOLD_PREPAID description: >- Charge payer when the set amount is reached or monthly billing cycle, whichever comes first, before the goods/service is delivered. - value: THRESHOLD_POSTPAID description: >- Charge payer when the set amount is reached or monthly billing cycle, whichever comes first, after the goods/service is delivered. - value: 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. - value: UNSCHEDULED_PREPAID description: >- Unscheduled card on file plan where the merchant can bill buyer upfront based on an agreed logic, but amount due and frequency can vary. Inclusive of automatic reload plans. - value: SUBSCRIPTION_PREPAID description: >- Subscription plan where the amount due and the billing frequency are fixed, and there is no defined duration with the payment due before the good/service is delivered. - value: SUBSCRIPTION_POSTPAID description: >- Subscription plan where the amount due and the billing frequency are fixed, and there is no defined duration with the payment due after the goods/services are delivered. - value: 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. - value: INSTALLMENT_PREPAID description: >- Merchant-managed installment plan when the amount to be paid and the billing frequency are fixed, but there is a defined number of payments with the payment due before the good/service is delivered. enum: - IMMEDIATE - DEFERRED - RECURRING_PREPAID - RECURRING_POSTPAID - THRESHOLD_PREPAID - THRESHOLD_POSTPAID - UNSCHEDULED_POSTPAID - UNSCHEDULED_PREPAID - SUBSCRIPTION_PREPAID - SUBSCRIPTION_POSTPAID - INSTALLMENT_POSTPAID - INSTALLMENT_PREPAID shipping: $ref: '#/components/schemas/shipping' 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_]+$ x-enumDescriptions: - value: MERCHANT description: >- The PayPal Payment Token will be used for future transaction directly with a merchant. - value: PLATFORM description: >- The PayPal Payment Token will be used for future transaction on a platform. A platform is typically a marketplace or a channel that a payer can purchase goods and services from multiple merchants. enum: - MERCHANT - PLATFORM customer_type: 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_]+$ x-enumDescriptions: - value: CONSUMER description: >- The customer vaulting the PayPal payment token is a consumer on the merchant / platform. - value: BUSINESS description: >- The customer vaulting the PayPal payment token is a business on merchant / platform. enum: - CONSUMER - BUSINESS payer_base: type: object title: Payer Base description: >- The customer who approves and pays for the order. The customer is also known as the payer. properties: email_address: $ref: '#/components/schemas/email' description: The email address of the payer. payer_id: $ref: '#/components/schemas/account_id' description: The PayPal-assigned ID for the payer. readOnly: true 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_with_type: type: object title: Phone With Type description: The phone information. properties: phone_type: $ref: '#/components/schemas/phone_type' phone_number: $ref: '#/components/schemas/phone_number' required: - phone_number address: description: >- The portable international postal address. Maps to [AddressValidationMetadata](https://github.com/googlei18n/libaddressinput/wiki/AddressValidationMetadata) and HTML 5.1 [Autofilling form controls: the autocomplete attribute](https://www.w3.org/TR/html51/sec-forms.html#autofilling-form-controls-the-autocomplete-attribute). type: object title: Portable Postal Address (Medium-Grained) properties: address_line_1: type: string description: >- The first line of the address, such as number and street, for example, `173 Drury Lane`. Needed for data entry, and Compliance and Risk checks. This field needs to pass the full address. maxLength: 300 address_line_2: type: string description: >- The second line of the address, for example, a suite or apartment number. maxLength: 300 admin_area_2: type: string description: A city, town, or village. Smaller than `admin_area_level_1`. maxLength: 120 admin_area_1: type: string description: >- The highest-level sub-division in a country, which is usually a province, state, or ISO-3166-2 subdivision. This data is formatted for postal delivery, for example, `CA` and not `California`. Value, by country, is: maxLength: 300 postal_code: type: string description: >- The postal code, which is the ZIP code or equivalent. Typically required for countries with a postal code or an equivalent. See [postal code](https://en.wikipedia.org/wiki/Postal_code). maxLength: 60 country_code: $ref: '#/components/schemas/country_code' required: - country_code 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}$ 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 definitions-7: title: Venmo Response description: Full representation of a Venmo Payment Token. type: object 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: $ref: '#/components/schemas/card_type' description: The payment card type. brand: $ref: '#/components/schemas/card_brand' description: The card brand or network. Typically used in the response. billing_address: $ref: '#/components/schemas/card_billing_address' 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' 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)$ 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 card_verification_status: title: Card Verification Status type: string minLength: 1 maxLength: 255 pattern: ^[0-9A-Z_]+$ description: Verification status of Card. x-enumDescriptions: - value: VERIFIED description: 'Card has been verified ' - value: FAILED description: 'Card verification has failed ' enum: - VERIFIED - FAILED 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: $ref: '#/components/schemas/card_brand' 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. deprecated: true time: $ref: '#/components/schemas/date_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 deprecated: true amount: $ref: '#/components/schemas/money' description: The amount used for card verification. processor_response: $ref: '#/components/schemas/processor_response' 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 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' 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: type: object title: Bin Details description: Bank Identification Number (BIN) details used to fund a payment. properties: bin: type: string description: >- The Bank Identification Number (BIN) signifies the number that is being used to identify the granular level details (except the PII information) of the card. pattern: ^[0-9]+$ maxLength: 25 minLength: 1 issuing_bank: type: string description: The issuer of the card instrument. minLength: 1 maxLength: 64 bin_country_code: $ref: '#/components/schemas/country_code-2' description: >- The [two-character ISO-3166-1 country code](/docs/integration/direct/rest/country-codes/) of the bank. products: $ref: '#/components/schemas/products_list' card_type: type: string title: Card Type description: Type of card. i.e Credit, Debit and so on. minLength: 1 maxLength: 255 pattern: ^[A-Z_]+$ x-enumDescriptions: - value: CREDIT description: A credit card. - value: DEBIT description: A debit card. - value: PREPAID description: A Prepaid card. - value: STORE description: A store card. - value: UNKNOWN description: Card type cannot be determined. enum: - CREDIT - DEBIT - PREPAID - STORE - UNKNOWN shipping: description: The shipping details. type: object title: Shipping Details properties: name: $ref: '#/components/schemas/shipping_name' phone_number: $ref: '#/components/schemas/shipping_phone_number' type: title: Fullfillment Type description: >- A classification for the method of purchase fulfillment (e.g shipping, in-store pickup, etc). Either `type` or `options` may be present, but not both. type: string minLength: 1 maxLength: 255 pattern: ^[0-9A-Z_]+$ x-enumDescriptions: - value: SHIPPING description: The payer intends to receive the items at a specified address. default: true - value: PICKUP_IN_PERSON description: DEPRECATED. Please use "PICKUP_FROM_PERSON" instead. - value: PICKUP_IN_STORE description: >- The payer intends to pick up the item(s) from the payee's physical store. Also termed as BOPIS, "Buy Online, Pick-up in Store". Seller protection is provided with this option. - value: PICKUP_FROM_PERSON description: >- The payer intends to pick up the item(s) from the payee in person. Also termed as BOPIP, "Buy Online, Pick-up in Person". Seller protection is not available, since the payer is receiving the item from the payee in person, and can validate the item prior to payment. enum: - SHIPPING - PICKUP_IN_PERSON - PICKUP_IN_STORE - PICKUP_FROM_PERSON address: $ref: '#/components/schemas/shipping_address' email: type: string description: >- The internationalized email address.
Note: Up to 64 characters are allowed before and 255 characters are allowed after the @ sign. However, the generally accepted maximum length for an email address is 254 characters. The pattern verifies that an unquoted @ sign exists.
format: merchant_common_email_address_v2 maxLength: 254 minLength: 3 pattern: >- (?:[a-zA-Z0-9!#$%&'*+/=?^_`{|}~-]+(?:\.[a-zA-Z0-9!#$%&'*+/=?^_`{|}~-]+)*|(?:[\x01-\x08\x0b\x0c\x0e-\x1f\x21\x23-\x5b\x5d-\x7f]|\[\x01-\x09\x0b\x0c\x0e-\x7f])*")@(?:(?:[a-zA-Z0-9](?:[a-zA-Z0-9-]*[a-zA-Z0-9])?\.)+[a-zA-Z0-9](?:[a-zA-Z0-9-]*[a-zA-Z0-9])?|\[(?:(?:(2(5[0-5]|[0-4][0-9])|1[0-9][0-9]|[1-9]?[0-9]))\.){3}(?:(2(5[0-5]|[0-4][0-9])|1[0-9][0-9]|[1-9]?[0-9])|[a-zA-Z0-9-]*[a-zA-Z0-9]:(?:[\x01-\x08\x0b\x0c\x0e-\x1f\x21-\x5a\x53-\x7f]|\[\x01-\x09\x0b\x0c\x0e-\x7f])+)\]) phone_type: type: string title: Phone Type description: The phone type. enum: - FAX - HOME - MOBILE - OTHER - PAGER phone_number: description: >- The phone number, in its canonical international [E.164 numbering plan format](https://www.itu.int/rec/T-REC-E.164/en). type: object title: Phone properties: national_number: type: string description: >- The national number, in its canonical international [E.164 numbering plan format](https://www.itu.int/rec/T-REC-E.164/en). The combined length of the country calling code (CC) and the national number must not be greater than 15 digits. The national number consists of a national destination code (NDC) and subscriber number (SN). minLength: 1 maxLength: 14 pattern: ^[0-9]{1,14}?$ required: - national_number card_billing_address: description: >- The portable international postal address. Maps to [AddressValidationMetadata](https://github.com/googlei18n/libaddressinput/wiki/AddressValidationMetadata) and HTML 5.1 [Autofilling form controls: the autocomplete attribute](https://www.w3.org/TR/html51/sec-forms.html#autofilling-form-controls-the-autocomplete-attribute). type: object title: Portable Postal Address (Medium-Grained) properties: address_line_1: type: string description: >- The first line of the address, such as number and street, for example, `173 Drury Lane`. Needed for data entry, and Compliance and Risk checks. This field needs to pass the full address. maxLength: 300 address_line_2: type: string description: >- The second line of the address, for example, a suite or apartment number. maxLength: 300 admin_area_2: type: string description: A city, town, or village. Smaller than `admin_area_level_1`. maxLength: 120 admin_area_1: type: string description: >- The highest-level sub-division in a country, which is usually a province, state, or ISO-3166-2 subdivision. This data is formatted for postal delivery, for example, `CA` and not `California`. Value, by country, is: maxLength: 300 postal_code: type: string description: >- The postal code, which is the ZIP code or equivalent. Typically required for countries with a postal code or an equivalent. See [postal code](https://en.wikipedia.org/wiki/Postal_code). maxLength: 60 country_code: $ref: '#/components/schemas/country_code' required: - country_code 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})$ 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 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 x-enumDescriptions: - value: A description: >- For Visa, Mastercard, or Discover transactions, the address matches but the zip code does not match. For American Express transactions, the card holder address is correct. - value: B description: >- For Visa, Mastercard, or Discover transactions, the address matches. International A. - value: C description: >- For Visa, Mastercard, or Discover transactions, no values match. International N. - value: D description: >- For Visa, Mastercard, or Discover transactions, the address and postal code match. International X. - value: E description: >- For Visa, Mastercard, or Discover transactions, not allowed for Internet or phone transactions. For American Express card holder, the name is incorrect but the address and postal code match. - value: F description: >- For Visa, Mastercard, or Discover transactions, the address and postal code match. UK-specific X. For American Express card holder, the name is incorrect but the address matches. - value: G description: >- For Visa, Mastercard, or Discover transactions, global is unavailable. Nothing matches. - value: I description: >- For Visa, Mastercard, or Discover transactions, international is unavailable. Not applicable. - value: M description: >- For Visa, Mastercard, or Discover transactions, the address and postal code match. For American Express card holder, the name, address, and postal code match. - value: 'N' description: >- For Visa, Mastercard, or Discover transactions, nothing matches. For American Express card holder, the address and postal code are both incorrect. - value: P description: >- For Visa, Mastercard, or Discover transactions, postal international Z. Postal code only. - value: R description: >- For Visa, Mastercard, or Discover transactions, re-try the request. For American Express, the system is unavailable. - value: S description: >- For Visa, Mastercard, Discover, or American Express, the service is not supported. - value: U description: >- For Visa, Mastercard, or Discover transactions, the service is unavailable. For American Express, information is not available. For Maestro, the address is not checked or the acquirer had no response. The service is not available. - value: W description: >- For Visa, Mastercard, or Discover transactions, whole ZIP code. For American Express, the card holder name, address, and postal code are all incorrect. - value: X description: >- For Visa, Mastercard, or Discover transactions, exact match of the address and the nine-digit ZIP code. For American Express, the card holder name, address, and postal code are all incorrect. - value: 'Y' description: >- For Visa, Mastercard, or Discover transactions, the address and five-digit ZIP code match. For American Express, the card holder address and postal code are both correct. - value: Z description: >- For Visa, Mastercard, or Discover transactions, the five-digit ZIP code matches but no address. For American Express, only the card holder postal code is correct. - value: 'Null' description: For Maestro, no AVS response was obtained. - value: '0' description: For Maestro, all address information matches. - value: '1' description: For Maestro, none of the address information matches. - value: '2' description: For Maestro, part of the address information matches. - value: '3' description: >- For Maestro, the merchant did not provide AVS information. It was not processed. - value: '4' description: >- For Maestro, the address was not checked or the acquirer had no response. The service is not available. enum: - A - B - C - D - E - F - G - I - M - 'N' - P - R - S - U - W - X - 'Y' - Z - 'Null' - '0' - '1' - '2' - '3' - '4' cvv_code: description: >- The card verification value code for for Visa, Discover, Mastercard, or American Express. type: string readOnly: true x-enumDescriptions: - value: E description: >- For Visa, Mastercard, Discover, or American Express, error - unrecognized or unknown response. - value: I description: >- For Visa, Mastercard, Discover, or American Express, invalid or null. - value: M description: >- For Visa, Mastercard, Discover, or American Express, the CVV2/CSC matches. - value: 'N' description: >- For Visa, Mastercard, Discover, or American Express, the CVV2/CSC does not match. - value: P description: >- For Visa, Mastercard, Discover, or American Express, it was not processed. - value: S description: >- For Visa, Mastercard, Discover, or American Express, the service is not supported. - value: U description: >- For Visa, Mastercard, Discover, or American Express, unknown - the issuer is not certified. - value: X description: >- For Visa, Mastercard, Discover, or American Express, no response. For Maestro, the service is not available. - value: All others description: For Visa, Mastercard, Discover, or American Express, error. - value: '0' description: For Maestro, the CVV2 matched. - value: '1' description: For Maestro, the CVV2 did not match. - value: '2' description: >- For Maestro, the merchant has not implemented CVV2 code handling. - value: '3' description: >- For Maestro, the merchant has indicated that CVV2 is not present on card. - value: '4' description: For Maestro, the service is not available. enum: - E - I - M - 'N' - P - S - U - X - All others - '0' - '1' - '2' - '3' - '4' network_transaction_reference_entity: type: object title: Network Transaction Reference Entity description: Previous network transaction reference including id and network. 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: $ref: '#/components/schemas/card_brand' description: Name of the card network through which the transaction was routed. time: $ref: '#/components/schemas/date_time' description: The date and time when the instrument was verified. readOnly: true required: - id 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_-]+$ country_code-2: type: string description: >- The [two-character ISO 3166-1 code](/api/rest/reference/country-codes/) that identifies the country or region.
Note: The country code for Great Britain is GB and not UK as used in the top-level domain names for that country. Use the `C2` country code for China worldwide for comparable uncontrolled price (CUP) method, bank card, and cross-border transactions.
format: ppaas_common_country_code_v2 maxLength: 2 minLength: 2 pattern: ^([A-Z]{2}|C2)$ products_list: type: array description: >- The type of card product assigned to the BIN by the issuer. These values are defined by the issuer and may change over time. Some examples include: PREPAID_GIFT, CONSUMER, CORPORATE. items: $ref: '#/components/schemas/products' minItems: 1 maxItems: 256 shipping_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 shipping_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 shipping_address: description: >- The portable international postal address. Maps to [AddressValidationMetadata](https://github.com/googlei18n/libaddressinput/wiki/AddressValidationMetadata) and HTML 5.1 [Autofilling form controls: the autocomplete attribute](https://www.w3.org/TR/html51/sec-forms.html#autofilling-form-controls-the-autocomplete-attribute). type: object title: Portable Postal Address (Medium-Grained) properties: address_line_1: type: string description: >- The first line of the address, such as number and street, for example, `173 Drury Lane`. Needed for data entry, and Compliance and Risk checks. This field needs to pass the full address. maxLength: 300 address_line_2: type: string description: >- The second line of the address, for example, a suite or apartment number. maxLength: 300 admin_area_2: type: string description: A city, town, or village. Smaller than `admin_area_level_1`. maxLength: 120 admin_area_1: type: string description: >- The highest-level sub-division in a country, which is usually a province, state, or ISO-3166-2 subdivision. This data is formatted for postal delivery, for example, `CA` and not `California`. Value, by country, is: maxLength: 300 postal_code: type: string description: >- The postal code, which is the ZIP code or equivalent. Typically required for countries with a postal code or an equivalent. See [postal code](https://en.wikipedia.org/wiki/Postal_code). maxLength: 60 country_code: $ref: '#/components/schemas/country_code' required: - country_code 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 three_d_secure_authentication_response: type: object title: Response of 3D Secure Authentication description: Results of 3D Secure Authentication. properties: authentication_status: $ref: '#/components/schemas/pares_status' description: The outcome of the issuer's authentication. enrollment_status: $ref: '#/components/schemas/enrolled' description: Status of authentication eligibility. products: type: string description: This value provides the category of the BIN. minLength: 1 maxLength: 255 pares_status: type: string minLength: 1 maxLength: 255 pattern: ^[0-9A-Z_]+$ description: >- Transactions status result identifier. The outcome of the issuer's authentication. x-enumDescriptions: - value: 'Y' description: Successful authentication. - value: 'N' description: Failed authentication / account not verified / transaction denied. - value: U description: Unable to complete authentication. - value: A description: Successful attempts transaction. - value: C description: Challenge required for authentication. - value: R description: >- Authentication rejected (merchant must not submit for authorization). - value: D description: Challenge required; decoupled authentication confirmed. - value: I description: Informational only; 3DS requestor challenge preference acknowledged. enum: - 'Y' - 'N' - U - A - C - R - D - I enrolled: type: string minLength: 1 maxLength: 255 pattern: ^[0-9A-Z_]+$ description: Status of Authentication eligibility. x-enumDescriptions: - value: 'Y' description: >- Yes. The bank is participating in 3-D Secure protocol and will return the ACSUrl. - value: 'N' description: No. The bank is not participating in 3-D Secure protocol. - value: U description: >- Unavailable. The DS or ACS is not available for authentication at the time of the request. - value: B description: >- Bypass. The merchant authentication rule is triggered to bypass authentication. enum: - 'Y' - 'N' - U - B securitySchemes: Oauth2: type: oauth2 description: Oauth 2.0 authentication flows: clientCredentials: tokenUrl: /v1/oauth2/token 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. ````