openapi: 3.0.3 info: title: Paypal Subscriptions Authorizations Setup-Tokens API description: You can use billing plans and subscriptions to create subscriptions that process recurring PayPal payments for physical or digital goods, or services. A plan includes pricing and billing cycle information that defines the amount and frequency of charge for a subscription. You can also define a fixed plan, such as a $5 basic plan or a volume- or graduated-based plan with pricing tiers based on the quantity purchased. For more information, see Subscriptions Overview. version: '1.6' contact: {} servers: - url: https://api-m.sandbox.paypal.com description: PayPal Sandbox Environment - url: https://api-m.paypal.com description: PayPal Live Environment tags: - name: Setup-Tokens description: Use the `/vault/setup-tokens` resource to create and retrieve temporary vault payment methods. paths: /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: Paypal 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' examples: setup_token_response: value: id: 5C991763VB2781612 customer: id: customer_4029352050 status: APPROVED payment_source: card: last_digits: '1111' expiry: 2027-02 name: John Doe billing_address: address_line_1: 2211 N First Street address_line_2: 17.3.160 admin_area_1: CA admin_area_2: San Jose postal_code: '95131' country_code: US links: - rel: self href: https://api-m.paypal.com/v3/vault/setup-tokens/5C991763VB2781612 method: GET encType: application/json - rel: confirm href: https://api-m.paypal.com/v3/vault/payment-token method: POST encType: application/json '201': description: A successful creation of setup token. content: application/json: schema: $ref: '#/components/schemas/setup_token_response' examples: setup_token_response: value: id: 5C991763VB2781612 customer: id: customer_4029352050 status: APPROVED payment_source: card: last_digits: '1111' expiry: 2027-02 name: John Doe billing_address: address_line_1: 2211 N First Street address_line_2: 17.3.160 admin_area_1: CA admin_area_2: San Jose postal_code: '95131' country_code: US links: - rel: self href: https://api-m.paypal.com/v3/vault/setup-tokens/5C991763VB2781612 method: GET encType: application/json - rel: confirm href: https://api-m.paypal.com/v3/vault/payment-token method: POST 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' '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/paypal_request_id' requestBody: content: application/json: schema: $ref: '#/components/schemas/setup_token_request' examples: setup_token_request: value: payment_source: card: number: '4111111111111111' expiry: 2027-02 name: John Doe billing_address: address_line_1: 2211 N First Street address_line_2: 17.3.160 admin_area_1: CA admin_area_2: San Jose postal_code: '95131' country_code: US experience_context: brand_name: YourBrandName locale: en-US return_url: https://example.com/returnUrl cancel_url: https://example.com/cancelUrl 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: Paypal 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' security: - Oauth2: - https://uri.paypal.com/services/vault/payment-tokens/read tags: - Setup-Tokens components: schemas: 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}))?$ shipping_detail: type: object description: The shipping details. title: Shipping Details properties: name: description: The name of the person to whom to ship the items. Supports only the `full_name` property. $ref: '#/components/schemas/name' type: description: The method by which the payer wants to get their items from the payee e.g shipping, in-person pickup. Either type or options but not both may be present. type: string minLength: 1 maxLength: 255 pattern: ^[0-9A-Z_]+$ enum: - SHIPPING - PICKUP_IN_PERSON address: description: The address of the person to whom to ship the items. Supports only the `address_line_1`, `address_line_2`, `admin_area_1`, `admin_area_2`, `postal_code`, and `country_code` properties. $ref: '#/components/schemas/address_portable' phone_type: type: string title: Phone Type description: The phone type. enum: - FAX - HOME - MOBILE - OTHER - PAGER 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: experience_context: $ref: '#/components/schemas/experience_context' 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 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}$ 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])$ customer: type: object title: Customer Request description: Customer in merchant's or partner's system of records. 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' 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 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: Customer in merchant's or partner's system of records. $ref: '#/components/schemas/customer' payment_source: description: The payment method to vault with the instrument details. properties: card: $ref: '#/components/schemas/card_request' paypal: $ref: '#/components/schemas/paypal_wallet_request' venmo: $ref: '#/components/schemas/venmo_request' token: $ref: '#/components/schemas/token_id_request' metadata: $ref: '#/components/schemas/metadata' required: - payment_source card_request: title: Card Request description: A Resource representing a request to vault a Card. allOf: - $ref: '#/components/schemas/card' - properties: 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/experience_context' 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_-]+$ instrument_id: type: string description: The identifier of the instrument. minLength: 1 maxLength: 256 pattern: ^[A-Za-z0-9-_.+=]+$ name: type: object title: Name description: The name of the party. properties: prefix: type: string description: The prefix, or title, to the party's name. maxLength: 140 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 middle_name: type: string description: When the party is a person, the party's middle name. Use also to store multiple middle names including the patronymic, or father's, middle name. maxLength: 140 suffix: type: string description: The suffix for the party's name. maxLength: 140 alternate_full_name: type: string description: DEPRECATED. The party's alternate name. Can be a business name, nickname, or any other name that cannot be split into first, last name. Required when the party is a business. maxLength: 300 full_name: type: string description: When the party is a person, the party's full name. maxLength: 300 metadata: {} 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 processor_response: type: object title: Processor Response description: The processor information. Might be required for payment requests, such as direct credit card transactions. properties: avs_code: description: The address verification code for Visa, Discover, Mastercard, or American Express transactions. type: string readOnly: true 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 enum: - E - I - M - N - P - S - U - X - All others - '0' - '1' - '2' - '3' - '4' response_code: description: Processor response code for the non-PayPal payment processor errors. type: string readOnly: true enum: - '0000' - 00N7 - '0100' - 0390 - '0500' - 0580 - 0800 - 0880 - 0R00 - '1000' - 10BR - '1300' - '1310' - '1312' - '1317' - '1320' - '1330' - '1335' - '1340' - '1350' - '1360' - '1370' - '1380' - '1382' - '1384' - '1390' - '1393' - '5100' - '5110' - '5120' - '5130' - '5135' - '5140' - '5150' - '5160' - '5170' - '5180' - '5190' - '5200' - '5210' - '5400' - '5500' - '5650' - '5700' - '5710' - '5800' - '5900' - '5910' - '5920' - '5930' - '6300' - '7600' - '7700' - '7710' - '7800' - '7900' - '8000' - '8010' - '8020' - '8030' - '8100' - '8110' - '8220' - '9100' - '9500' - '9510' - '9520' - '9530' - '9540' - '9600' - PCNR - PCVV - PPAD - PPAE - PPAG - PPAI - PPAR - PPAU - PPAV - PPAX - PPBG - PPC2 - PPCE - PPCO - PPCR - PPCT - PPCU - PPD3 - PPDC - PPDI - PPDV - PPEF - PPEL - PPER - PPEX - PPFE - PPFI - PPFR - PPFV - PPGR - PPH1 - PPIF - PPII - PPIM - PPIT - PPLR - PPLS - PPMB - PPMC - PPMD - PPNC - PPNL - PPNT - PPPH - PPPI - PPPM - PPQC - PPRE - PPRF - PPRR - PPS0 - PPS1 - PPS2 - PPS3 - PPS4 - PPS5 - PPS6 - PPSC - PPSD - PPSE - PPTE - PPTF - PPTI - PPTR - PPTT - PPTV - PPUA - PPUC - PPUE - PPUI - PPUP - PPUR - PPVC - PPVE - PPVT payment_advice_code: description: The declined payment transactions might have payment advice codes. The card networks, like Visa and Mastercard, return payment advice codes. type: string readOnly: true enum: - '01' - '02' - '03' - '21' 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: 300 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_]+$ vault_instruction: description: Vault Instruction on action to be performed after a successful payer approval. $ref: '#/components/schemas/vault_instruction' 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])$ vault_id: type: string description: The PayPal-generated ID for the vault token. minLength: 1 maxLength: 36 pattern: ^[0-9a-zA-Z_-]+$ ordinal: type: integer description: Ordinal number for sorting. minimum: 1 maximum: 99 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/experience_context' venmo_response: title: Venmo Response description: Full representation of a Venmo Payment Token. type: object allOf: - $ref: '#/components/schemas/wallet_base' - readOnly: true $ref: '#/components/schemas/payer' - properties: user_name: description: The Venmo username, as chosen by the user. type: string pattern: ^[-a-zA-Z0-9_]*$ minLength: 1 maxLength: 50 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). Supports only the `national_number` property. $ref: '#/components/schemas/phone' required: - phone_number 3ds_result: {} 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 address_entity: {} 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-Z_-]+$ type: type: string description: The tokenization method that generated the ID. minLength: 1 maxLength: 255 pattern: ^[0-9A-Z_-]+$ enum: - BILLING_AGREEMENT attributes: description: The auxiliary details of the token. $ref: '#/components/schemas/token_attributes' required: - id - type card_response: type: object title: Card Response 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: description: The billing address for this card. Supports only the `address_line_1`, `address_line_2`, `admin_area_1`, `admin_area_2`, `postal_code`, and `country_code` properties. $ref: '#/components/schemas/address_entity' verification_status: description: Card Verification status. $ref: '#/components/schemas/card_verification_status' verification: $ref: '#/components/schemas/card_verification_details' address_portable: type: object title: Portable Postal Address (Medium-Grained) description: 'The portable international postal address. Maps to [AddressValidationMetadata](https://github.com/googlei18n/libaddressinput/wiki/AddressValidationMetadata) and HTML 5.1 [Autofilling form controls: the autocomplete attribute](https://www.w3.org/TR/html51/sec-forms.html#autofilling-form-controls-the-autocomplete-attribute).' properties: address_line_1: type: string description: The first line of the address. For example, number or street. For example, `173 Drury Lane`. Required for data entry and compliance and risk checks. Must contain the full address. maxLength: 300 address_line_2: type: string description: The second line of the address. For example, suite or apartment number. maxLength: 300 address_line_3: type: string description: The third line of the address, if needed. For example, a street complement for Brazil, direction text, such as `next to Walmart`, or a landmark in an Indian address. maxLength: 100 admin_area_4: type: string description: The neighborhood, ward, or district. Smaller than `admin_area_level_3` or `sub_locality`. Value is: maxLength: 100 admin_area_3: type: string description: A sub-locality, suburb, neighborhood, or district. Smaller than `admin_area_level_2`. Value is: maxLength: 100 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. Format 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' address_details: type: object title: Address Details description: The non-portable additional address details that are sometimes needed for compliance, risk, or other scenarios where fine-grain address information might be needed. Not portable with common third party and open source. Redundant with core fields.
For example, `address_portable.address_line_1` is usually a combination of `address_details.street_number`, `street_name`, and `street_type`. properties: street_number: type: string description: The street number. maxLength: 100 street_name: type: string description: The street name. Just `Drury` in `Drury Lane`. maxLength: 100 street_type: type: string description: The street type. For example, avenue, boulevard, road, or expressway. maxLength: 100 delivery_service: type: string description: The delivery service. Post office box, bag number, or post office name. maxLength: 100 building_name: type: string description: A named locations that represents the premise. Usually a building name or number or collection of buildings with a common name or number. For example, Craven House. maxLength: 100 sub_building: type: string description: The first-order entity below a named building or location that represents the sub-premises. Usually a single building within a collection of buildings with a common name. Can be a flat, story, floor, room, or apartment. maxLength: 100 required: - country_code paypal_wallet_response: title: PayPal Wallet Response description: Full representation of a PayPal Payment Token. type: object allOf: - $ref: '#/components/schemas/wallet_base' - readOnly: true $ref: '#/components/schemas/payer' - 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' 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. information_link: type: string description: The information link, or URI, that shows detailed information about this error for the developer. readOnly: true details: type: array description: An array of additional details about the error. items: $ref: '#/components/schemas/error_details-2' links: type: array description: An array of request-related [HATEOAS links](/api/rest/responses/#hateoas-links). readOnly: true items: $ref: '#/components/schemas/link_description' readOnly: true required: - name - message - debug_id 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: Transaction Identifier as given by the network to indicate a previously executed CIT authorization. Only present when authorization is successful for a verification. type: string minLength: 1 maxLength: 1024 pattern: ^[a-zA-Z0-9-_@.:&+=*^'~#!$%()]+$ time: description: The date and time when the instrument was verified. readOnly: true $ref: '#/components/schemas/date_time' amount: description: The amount used for card verification. $ref: '#/components/schemas/money' processor_response: description: The processor information. $ref: '#/components/schemas/processor_response' three_d_secure: $ref: '#/components/schemas/3ds_result' currency_code: description: The [three-character ISO-4217 currency code](/api/rest/reference/currency-codes/) that identifies the currency. type: string format: ppaas_common_currency_code_v2 minLength: 3 maxLength: 3 token_attributes: {} card: type: object title: Card description: The payment card to use to fund a payment. Can be a credit or debit card. properties: id: description: The PayPal-generated ID for the card. readOnly: true $ref: '#/components/schemas/instrument_id' 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). $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 last_digits: type: string description: The last digits of the payment card. pattern: ^[0-9]{2,4}$ minLength: 2 maxLength: 4 readOnly: true card_type: description: The card brand or network. Typically used in the response. readOnly: true $ref: '#/components/schemas/card_brand' deprecated: 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 billing address for this card. Supports only the `address_line_1`, `address_line_2`, `admin_area_1`, `admin_area_2`, `postal_code`, and `country_code` properties. $ref: '#/components/schemas/address_portable' 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' country_code: 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)$ 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 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. 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_time: type: string description: The date and time, in [Internet date and time format](https://tools.ietf.org/html/rfc3339#section-5.6). Seconds are required while fractional seconds are optional.
Note: The regular expression provides guidance but does not reject all invalid dates.
format: ppaas_date_time_v3 minLength: 20 maxLength: 64 pattern: ^[0-9]{4}-(0[1-9]|1[0-2])-(0[1-9]|[1-2][0-9]|3[0-1])[T,t]([0-1][0-9]|2[0-3]):[0-5][0-9]:([0-5][0-9]|60)([.][0-9]+)?([Zz]|[+-][0-9]{2}:[0-9]{2})$ card_verification_method: title: Card Verification Method type: string description: The verification method of the card. minLength: 1 maxLength: 255 pattern: ^[0-9A-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 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' ordinal: description: The ordinal number of customers' payment source for sorting. $ref: '#/components/schemas/ordinal' customer: description: Customer in merchant's or partner's system of records. $ref: '#/components/schemas/customer' status: description: The status of the payment token. $ref: '#/components/schemas/payment_token_status' payment_source: description: The setup payment method details. properties: card: $ref: '#/components/schemas/card_response' paypal: $ref: '#/components/schemas/paypal_wallet_response' venmo: $ref: '#/components/schemas/venmo_response' links: 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' card_verification_status: title: Card Verification Status type: string minLength: 1 maxLength: 255 pattern: ^[0-9A-Z_]+$ description: Verification status of Card. 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 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])+)\]) 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: ^[a-zA-Z0-9_'\-., :;\!?"]*$ shipping: description: The shipping address for the Payer. $ref: '#/components/schemas/shipping_detail' 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_]+$ 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_]+$ tax_info: type: object description: The tax ID of the customer. The customer is also known as the payer. Both `tax_id` and `tax_id_type` are required. title: Tax Information properties: tax_id: type: string description: The customer's tax ID value. minLength: 1 maxLength: 14 pattern: ([a-zA-Z0-9]) tax_id_type: type: string description: The customer's tax ID type. minLength: 1 maxLength: 14 pattern: ^[A-Z0-9_]+$ enum: - BR_CPF - BR_CNPJ required: - tax_id - tax_id_type payer: type: object title: Customer description: The customer who approves and pays for the order. The customer is also known as the payer. format: payer_v1 allOf: - $ref: '#/components/schemas/payer_base' - properties: name: description: The name of the payer. Supports only the `given_name` and `surname` properties. $ref: '#/components/schemas/name' 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' birth_date: description: The birth date of the payer in `YYYY-MM-DD` format. $ref: '#/components/schemas/date_no_time' tax_info: description: The tax information of the payer. Required only for Brazilian payer's. Both `tax_id` and `tax_id_type` are required. $ref: '#/components/schemas/tax_info' address: description: The address of the payer. Supports only the `address_line_1`, `address_line_2`, `admin_area_1`, `admin_area_2`, `postal_code`, and `country_code` properties. Also referred to as the billing address of the customer. $ref: '#/components/schemas/address_portable' parameters: 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_-]+$ paypal_request_id: name: PayPal-Request-Id description: The server stores keys for 3 hours. in: header required: true schema: type: string securitySchemes: Oauth2: type: oauth2 description: Oauth 2.0 authentication flows: clientCredentials: tokenUrl: /v1/oauth2/token scopes: https://uri.paypal.com/services/subscriptions: Manage plan & subscription externalDocs: url: https://developer.paypal.com/docs/api/subscriptions/v1/