PayPal Setup-Tokens API

openapi: 3.2.0
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 <a href="/docs/subscriptions/">Subscriptions Overview</a>.
  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:
    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
    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
    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:<ul><li>An integer for currencies like `JPY` that are not typically fractional.</li><li>A decimal fraction for currencies like `TND` that are subdivided into thousandths.</li></ul>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
    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_-]+$
    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.<blockquote><strong>Note:</strong> The regular expression provides guidance but does not reject all invalid dates.</blockquote>
      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})$
    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
    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}$
    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
    vault_id:
      type: string
      description: The PayPal-generated ID for the vault token.
      minLength: 1
      maxLength: 36
      pattern: ^[0-9a-zA-Z_-]+$
    phone_type:
      type: string
      title: Phone Type
      description: The phone type.
      enum:
      - FAX
      - HOME
      - MOBILE
      - OTHER
      - PAGER
    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'
    email:
      type: string
      description: The internationalized email address.<blockquote><strong>Note:</strong> Up to 64 characters are allowed before and 255 characters are allowed after the <code>@</code> sign. However, the generally accepted maximum length for an email address is 254 characters. The pattern verifies that an unquoted <code>@</code> sign exists.</blockquote>
      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])+)\])
    card_verification_status:
      title: Card Verification Status
      type: string
      minLength: 1
      maxLength: 255
      pattern: ^[0-9A-Z_]+$
      description: Verification status of Card.
    metadata: {}
    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'
    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
    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: 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
    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
    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'
    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
    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
    token_attributes: {}
    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
    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'
    ordinal:
      type: integer
      description: Ordinal number for sorting.
      minimum: 1
      maximum: 99
    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])$
    card_verification_method:
      title: Card Verification Method
      type: string
      description: The verification method of the card.
      minLength: 1
      maxLength: 255
      pattern: ^[0-9A-Z_]+$
    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'
    address_entity: {}
    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}))?$
    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_]+$
    instrument_id:
      type: string
      description: The identifier of the instrument.
      minLength: 1
      maxLength: 256
      pattern: ^[A-Za-z0-9-_.+=]+$
    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])$
    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'
    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 <a href="https://www.paypal.com/cgi-bin/customerprofileweb?cmd=_profile-website-payments">**Profile & Settings**</a> 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'
    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
    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-r

# --- truncated at 32 KB (48 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/paypal/refs/heads/main/openapi/paypal-setup-tokens-api-openapi.yml