openapi: 3.0.3
info:
  title: Paypal 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.<br><br>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.<br><br>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.1'
  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: 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.
externalDocs:
  url: https://developer.paypal.com/docs/api/vault/v3/
paths:
  "/v3/vault/payment-tokens":
    post:
      description: Creates a Payment Token from the given payment source and adds it to the Vault of the associated customer.
      summary: Paypal Create payment token for a given payment source
      operationId: payment-tokens.create
      responses:
        '200':
          description: Idempotent response for a successful creation of payment token.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/payment_token_response"
              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"
      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
      security:
        - Oauth2:
            - https://uri.paypal.com/services/vault/payment-tokens/readwrite
      tags:
        - Payment-Tokens
    get:
      description: Returns all payment tokens for a customer.
      summary: Paypal List all payment tokens
      operationId: customer.payment-tokens.get
      responses:
        '200':
          description: Successful execution.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/customer_vault_payment_tokens_response"
              examples:
                customer_vault_payment_tokens_response:
                  value:
                    customer:
                      id: customer_4029352050
                    payment_tokens:
                      - id: 8kk8451t
                        customer:
                          id: customer_4029352050
                        payment_source:
                          card:
                            brand: VISA
                            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_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
                      - id: fgh6561t
                        customer:
                          id: customer_4029352050
                        payment_source:
                          paypal:
                            description: Description for PayPal to be shown to PayPal payer
                            email_address: john.doe@example.com
                            account_id: VYYFH3WJ4JPJQ
                            shipping:
                              name:
                                full_name: John Doe
                              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
                            usage_pattern: IMMEDIATE
                            usage_type: MERCHANT
                            customer_type: CONSUMER
                            name:
                              given_name: John
                              surname: Doe
                            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/fgh6561t
                            method: GET
                            encType: application/json
                          - rel: delete
                            href: https://api-m.paypal.com/v3/vault/payment-tokens/fgh6561t
                            method: DELETE
                            encType: application/json
                      - id: hg654s1t
                        customer:
                          id: customer_4029352050
                        payment_source:
                          venmo:
                            description: Description for Venmo to be shown to Venmo payer
                            shipping:
                              name:
                                full_name: John Doe
                              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
                            usage_pattern: IMMEDIATE
                            usage_type: MERCHANT
                            customer_type: CONSUMER
                            email_address: john.doe@example.com
                            user_name: johndoe
                            name:
                              given_name: John
                              surname: Doe
                            account_id: VYYFH3WJ4JPJQ
                            address:
                              address_line_1: PayPal
                              address_line_2: 2211 North 1st Street
                              admin_area_1: CA
                              admin_area_2: San Jose
                              postal_code: '96112'
                              country_code: US
                        links:
                          - rel: self
                            href: https://api-m.paypal.com/v3/vault/payment-tokens/hg654s1t
                            method: GET
                            encType: application/json
                          - rel: delete
                            href: https://api-m.paypal.com/v3/vault/payment-tokens/hg654s1t
                            method: DELETE
                            encType: application/json
                    links:
                      - rel: self
                        href: https://api-m.paypal.com/v3/vault/payment-tokens?customer_id=customer_4029352050&page=1&page_size=5&total_required=false
                        method: GET
                        encType: application/json
                      - rel: first
                        href: https://api-m.paypal.com/v3/vault/payment-tokens?customer_id=customer_4029352050&page=1&page_size=5&total_required=false
                        method: GET
                        encType: application/json
                      - rel: last
                        href: https://api-m.paypal.com/v3/vault/payment-tokens?customer_id=customer_4029352050&page=1&page_size=5&total_required=false
                        method: GET
                        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"
        '500':
          description: An internal server error has occurred.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/error"
      parameters:
        - "$ref": "#/components/parameters/customer_id"
        - "$ref": "#/components/parameters/page_size"
        - "$ref": "#/components/parameters/page"
        - "$ref": "#/components/parameters/total_required"
      security:
        - Oauth2:
            - https://uri.paypal.com/services/vault/payment-tokens/readwrite
      tags:
        - Payment-Tokens
  "/v3/vault/payment-tokens/{id}":
    get:
      description: Returns a readable representation of vaulted payment source associated with the payment token id.
      summary: Paypal Retrieve a payment token
      operationId: payment-tokens.get
      responses:
        '200':
          description: Successful execution.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/payment_token_response"
        '403':
          description: Authorization failed due to insufficient permissions.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/error"
        '404':
          description: The specified resource does not exist.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/error"
        '422':
          description: The requested action could not be performed, semantically incorrect, or failed business validation.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/error"
        '500':
          description: An internal server error has occurred.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/error"
      parameters:
        - "$ref": "#/components/parameters/id"
      security:
        - Oauth2:
            - https://uri.paypal.com/services/vault/payment-tokens/readwrite
      tags:
        - Payment-Tokens
    delete:
      description: Delete the payment token associated with the payment token id.
      summary: Paypal Delete payment token
      operationId: payment-tokens.delete
      responses:
        '204':
          description: The server has successfully executed the method, but there is no entity body to return.
        '400':
          description: Request is not well-formed, syntactically incorrect, or violates schema.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/error"
        '403':
          description: Authorization failed due to insufficient permissions.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/error"
        '500':
          description: An internal server error has occurred.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/error"
      parameters:
        - "$ref": "#/components/parameters/id"
      security:
        - Oauth2:
            - https://uri.paypal.com/services/vault/payment-tokens/readwrite
      tags:
        - Payment-Tokens
  "/v3/vault/setup-tokens":
    post:
      description: Creates a Setup Token from the given payment source and adds it to the Vault of the associated customer.
      summary: 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:
  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.
  schemas:
    error_details:
      title: Error Details
      type: object
      description: The error details. Required for client-side `4XX` errors.
      properties:
        field:
          type: string
          description: The field that caused the error. If this field is in the body, set this value to the field's JSON pointer value. Required for client-side errors.
        value:
          type: string
          description: The value of the field that caused the error.
        location:
          "$ref": "#/components/schemas/error_location"
        issue:
          type: string
          description: The unique, fine-grained application-level error code.
        description:
          type: string
          description: The human-readable description for an issue. The description can change over the lifetime of an API, so clients must not depend on this value.
      required:
        - issue
    error_location:
      type: string
      description: The location of the field that caused the error. Value is `body`, `path`, or `query`.
      enum:
        - body
        - path
        - query
      default: body
    error_link_description:
      title: Link Description
      description: The request-related [HATEOAS link](/api/rest/responses/#hateoas-links) information.
      type: object
      required:
        - href
        - rel
      properties:
        href:
          description: The complete target URL. To make the related call, combine the method with this [URI Template-formatted](https://tools.ietf.org/html/rfc6570) link. For pre-processing, include the `$`, `(`, and `)` characters. The `href` is the key HATEOAS component that links a completed call with a subsequent call.
          type: string
          minLength: 0
          maxLength: 20000
          pattern: "^.*$"
        rel:
          description: The [link relation type](https://tools.ietf.org/html/rfc5988#section-4), which serves as an ID for a link that unambiguously describes the semantics of the link. See [Link Relations](https://www.iana.org/assignments/link-relations/link-relations.xhtml).
          type: string
          minLength: 0
          maxLength: 100
          pattern: "^.*$"
        method:
          description: The HTTP method required to make the related call.
          type: string
          minLength: 3
          maxLength: 6
          pattern: "^[A-Z]*$"
          enum:
            - GET
            - POST
            - PUT
            - DELETE
            - PATCH
    error_400:
      type: object
      title: Bad Request Error
      description: Request is not well-formed, syntactically incorrect, or violates schema.
      properties:
        name:
          type: string
          enum:
            - INVALID_REQUEST
        message:
          type: string
          enum:
            - Request is not well-formed, syntactically incorrect, or violates schema.
        details:
          type: array
          items:
            "$ref": "#/components/schemas/error_details"
        debug_id:
          type: string
          description: The PayPal internal ID. Used for correlation purposes.
        links:
          description: An array of request-related [HATEOAS links](https://en.wikipedia.org/wiki/HATEOAS).
          type: array
          minItems: 0
          maxItems: 10000
          items:
            "$ref": "#/components/schemas/error_link_description"
    error_401:
      type: object
      title: Unauthorized Error
      description: Authentication failed due to missing Authorization header, or invalid authentication credentials.
      properties:
        name:
          type: string
          enum:
            - AUTHENTICATION_FAILURE
        message:
          type: string
          enum:
            - Authentication failed due to missing authorization header, or invalid authentication credentials.
        details:
          type: array
          items:
            "$ref": "#/components/schemas/error_details"
        debug_id:
          type: string
          description: The PayPal internal ID. Used for correlation purposes.
        links:
          description: An array of request-related [HATEOAS links](https://en.wikipedia.org/wiki/HATEOAS).
          type: array
          minItems: 0
          maxItems: 10000
          items:
            "$ref": "#/components/schemas/error_link_description"
    error_403:
      type: object
      title: Not Authorized Error
      description: 'The client is not authorized to access this resource, although it may have valid credentials. '
      properties:
        name:
          type: string
          enum:
            - NOT_AUTHORIZED
        message:
          type: string
          enum:
            - Authorization failed due to insufficient permissions.
        details:
          type: array
          items:
            "$ref": "#/components/schemas/error_details"
        debug_id:
          type: string
          description: The PayPal internal ID. Used for correlation purposes.
        links:
          description: An array of request-related [HATEOAS links](https://en.wikipedia.org/wiki/HATEOAS).
          type: array
          minItems: 0
          maxItems: 10000
          items:
            "$ref": "#/components/schemas/error_link_description"
    error_404:
      type: object
      title: Not found Error
      description: The server has not found anything matching the request URI. This either means that the URI is incorrect or the resource is not available.
      properties:
        name:
          type: string
          enum:
            - RESOURCE_NOT_FOUND
        message:
          type: string
          enum:
            - The specified resource does not exist.
        details:
          type: array
          items:
            "$ref": "#/components/schemas/error_details"
        debug_id:
          type: string
          description: The PayPal internal ID. Used for correlation purposes.
        links:
          description: An array of request-related [HATEOAS links](https://en.wikipedia.org/wiki/HATEOAS).
          type: array
          minItems: 0
          maxItems: 10000
          items:
            "$ref": "#/components/schemas/error_link_description"
    error_409:
      type: object
      title: Resource Conflict Error
      description: The server has detected a conflict while processing this request.
      properties:
        name:
          type: string
          enum:
            - RESOURCE_CONFLICT
        message:
          type: string
          enum:
            - The server has detected a conflict while processing this request.
        details:
          type: array
          items:
            "$ref": "#/components/schemas/error_details"
        debug_id:
          type: string
          description: The PayPal internal ID. Used for correlation purposes.
        links:
          description: An array of request-related [HATEOAS links](https://en.wikipedia.org/wiki/HATEOAS).
          type: array
          minItems: 0
          maxItems: 10000
          items:
            "$ref": "#/components/schemas/error_link_description"
    error_415:
      type: object
      title: Unsupported Media Type Error
      description: The server does not support the request payload's media type.
      properties:
        name:
          type: string
          enum:
            - UNSUPPORTED_MEDIA_TYPE
        message:
          type: string
          enum:
            - The server does not support the request payload's media type.
        details:
          type: array
          items:
            "$ref": "#/components/schemas/error_details"
        debug_id:
          type: string
          description: The PayPal internal ID. Used for correlation purposes.
        links:
          description: An array of request-related [HATEOAS links](https://en.wikipedia.org/wiki/HATEOAS).
          type: array
          minItems: 0
          maxItems: 10000
          items:
            "$ref": "#/components/schemas/error_link_description"
    error_422:
      type: object
      title: Unprocessable Entity Error
      description: The requested action cannot be performed and may require interaction with APIs or processes outside of the current request. This is distinct from a 500 response in that there are no systemic problems limiting the API from performing the request.
      properties:
        name:
          type: string
          enum:
            - UNPROCESSABLE_ENTITY
        message:
          type: string
          enum:
            - The requested action could not be performed, semantically incorrect, or failed business validation.
        details:
          type: array
          items:
            "$ref": "#/components/schemas/error_details"
        debug_id:
          type: string
          description: The PayPal internal ID. Used for correlation purposes.
        links:
          description: An array of request-related [HATEOAS links](https://en.wikipedia.org/wiki/HATEOAS).
          type: array
          minItems: 0
          maxItems: 10000
          items:
            "$ref": "#/components/schemas/error_link_description"
    error_500:
      type: object
      title: Internal Server Error
      description: This is either a system or application error, and generally indicates that although the client appeared to provide a correct request, something unexpected has gone wrong on the server.
      properties:
        name:
          type: string
          enum:
            - INTERNAL_SERVER_ERROR
        message:
          type: string
          enum:
            - An internal server error occurred.
        debug_id:
          type: string
          description: The PayPal internal ID. Used for correlation purposes.
        links:
          description: An array of request-related [HATEOAS links](https://en.wikipedia.org/wiki/HATEOAS).
          type: array
          minItems: 0
          maxItems: 10000
          items:
            "$ref": "#/components/schemas/error_link_description"
      example:
        name: INTERNAL_SERVER_ERROR
        message: An internal server error occurred.
        debug_id: 90957fca61718
        links:
          - href: https://developer.paypal.com/api/orders/v2/#error-INTERNAL_SERVER_ERROR
            rel: information_link
    error_503:
      type: object
      title: Service Unavailable Error
      description: The server is temporarily unable to handle the request, for example, because of planned maintenance or downtime.
      properties:
        name:
          type: string
          enum:
            - SERVICE_UNAVAILABLE
        message:
          type: string
          enum:
            - Service Unavailable.
        debug_id:
          type: string
          description: The PayPal internal ID. Used for correlation purposes.
        links:
          description: An array of request-related [HATEOAS links](https://en.wikipedia.org/wiki/HATEOAS).
          type: array
          minItems: 0
          maxItems: 10000
          items:
            "$ref": "#/components/schemas/error_link_description"
      example:
        name: SERVICE_UNAVAILABLE
        message: Service Unavailable.
        debug_id: 90957fca61718
        information_link: https://developer.paypal.com/docs/api/orders/v2/#error-SERVICE_UNAVAILABLE
    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_-]+$"
    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"
    vault_id:
      type: string
      description: The PayPal-generated ID for the vault token.
      minLength: 1
      maxLength: 36
      pattern: "^[0-9a-zA-Z_-]+$"
    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
    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])$"
    address_entity: {}
    card_verification_status:
      title: Card Verification Status
      type: string
      minLength: 1
      maxLength: 255
      pattern: "^[0-9A-Z_]+$"
      description: Verification status of Card.
    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})$"
    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
    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
    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'
    3ds_result: {}
    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"
    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"
    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
    country_code:
      type: string
      description: The [two-character ISO 3166-1 code](/api/rest/reference/country-codes/) that identifies the country or region.<blockquote><strong>Note:</strong> The country code for Great Britain is <code>GB</code> and not <code>UK</code> 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.</blockquote>
      format: ppaas_common_country_code_v2
      maxLength: 2
      minLength: 2
      pattern: "^([A-Z]{2}|C2)$"
    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:<ul><li>The postal sorting code for Guernsey and many French territories, such as French Guiana.</li><li>The fine-grained administrative levels in China.</li></ul>
          maxLength: 100
        admin_area_3:
          type: string
          description: A sub-locality, suburb, neighborhood, or district. Smaller than `admin_area_level_2`. Value is:<ul><li>Brazil. Suburb, bairro, or neighborhood.</li><li>India. Sub-locality or district. Street name information is not always available but a sub-locality or district can be a very small area.</li></ul>
          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:<ul><li>UK. A county.</li><li>US. A state.</li><li>Canada. A province.</li><li>Japan. A prefecture.</li><li>Switzerland. A kanton.</li></ul>
          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.<br/>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, <code>Craven House</code>.
              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
    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"
    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_]+$"
    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])+)\])
    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}$"
    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"
    phone_type:
      type: string
      title: Phone Type
      description: The phone type.
      enum:
        - FAX
        - HOME
        - MOBILE
        - OTHER
        - PAGER
    phone:
      type: object
      title: Phone
      description: The phone number, in its canonical international [E.164 numbering plan format](https://www.itu.int/rec/T-REC-E.164/en).
      properties:
        country_code:
          type: string
          description: The country calling code (CC), in its canonical international [E.164 numbering plan format](https://www.itu.int/rec/T-REC-E.164/en). The combined length of the CC and the national number must not be greater than 15 digits. The national number consists of a national destination code (NDC) and subscriber number (SN).
          minLength: 1
          maxLength: 3
          pattern: "^[0-9]{1,3}?$"
        national_number:
          type: string
          description: The national number, in its canonical international [E.164 numbering plan format](https://www.itu.int/rec/T-REC-E.164/en). The combined length of the country calling code (CC) and the national number must not be greater than 15 digits. The national number consists of a national destination code (NDC) and subscriber number (SN).
          minLength: 1
          maxLength: 14
          pattern: "^[0-9]{1,14}?$"
        extension_number:
          type: string
          description: The extension number.
          minLength: 1
          maxLength: 15
          pattern: "^[0-9]{1,15}?$"
      required:
        - country_code
        - national_number
    phone_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
    date_no_time:
      type: string
      description: The stand-alone date, in [Internet date and time format](https://tools.ietf.org/html/rfc3339#section-5.6). To represent special legal values, such as a date of birth, you should use dates with no associated time or time-zone data. Whenever possible, use the standard `date_time` type. This regular expression does not validate all dates. For example, February 31 is valid and nothing is known about leap years.
      format: ppaas_date_notime_v2
      minLength: 10
      maxLength: 10
      pattern: "^[0-9]{4}-(0[1-9]|1[0-2])-(0[1-9]|[1-2][0-9]|3[0-1])$"
    tax_info:
      type: object
      description: The tax ID of the customer. The customer is also known as the payer. Both `tax_id` and `tax_id_type` are required.
      title: Tax 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 <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"
    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"
    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
    instrument_id:
      type: string
      description: The identifier of the instrument.
      minLength: 1
      maxLength: 256
      pattern: "^[A-Za-z0-9-_.+=]+$"
    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
    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"
    apple_pay_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.
      allOf:
        - "$ref": "#/components/schemas/card"
    apple_pay_payment_token_response:
      type: object
      title: Apple Pay Response
      description: A resource representing a response for Apple Pay.
      properties:
        card:
          description: Card data for the card linked to the apple pay token.
          "$ref": "#/components/schemas/apple_pay_card"
    ach_debit_response: {}
    ach_debit_verification_status:
      description: The ach debit verification status.
      type: string
      default: NOT_VERIFIED
      minLength: 1
      maxLength: 255
    ach_debit_response-2:
      title: ACH Debit Response
      description: A Resource representing a response of vaulted a ACH Debit Account.
      allOf:
        - "$ref": "#/components/schemas/ach_debit_response"
        - properties:
            verification_status:
              description: ACH Debit Verification Status
              "$ref": "#/components/schemas/ach_debit_verification_status"
    bank_response:
      title: Bank Response
      description: Full representation of a Bank Payment Token.
      type: object
      properties:
        ach_debit:
          description: ACH Debit Response.
          "$ref": "#/components/schemas/ach_debit_response-2"
    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
    payment_token_response:
      title: Payment Token Response
      description: Full representation of a saved payment token.
      type: object
      properties:
        id:
          description: The PayPal-generated ID for the vault token.
          "$ref": "#/components/schemas/vault_id"
        customer:
          description: Customer in merchant's or partner's system of records.
          "$ref": "#/components/schemas/customer"
        payment_source:
          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"
            bank:
              "$ref": "#/components/schemas/bank_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"
    customer_vault_payment_tokens_response:
      title: Vault of a customer
      description: Collection of payment tokens saved for a given customer.
      properties:
        total_items:
          type: integer
          description: Total number of items.
          minimum: 1
          maximum: 50
        total_pages:
          type: integer
          description: Total number of pages.
          minimum: 1
          maximum: 10
        customer:
          "$ref": "#/components/schemas/customer"
        payment_tokens:
          type: array
          minItems: 0
          maxItems: 64
          items:
            description: Each token in this collection represents a payment token.
            "$ref": "#/components/schemas/payment_token_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"
    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
    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_method:
      title: Card Verification Method
      type: string
      description: The verification method of the card.
      minLength: 1
      maxLength: 255
      pattern: "^[0-9A-Z_]+$"
    language:
      type: string
      description: The [language tag](https://tools.ietf.org/html/bcp47#section-2) for the language in which to localize the error-related strings, such as messages, issues, and suggested actions. The tag is made up of the [ISO 639-2 language code](https://www.loc.gov/standards/iso639-2/php/code_list.php), the optional [ISO-15924 script tag](https://www.unicode.org/iso15924/codelists.html), and the [ISO-3166 alpha-2 country code](/api/rest/reference/country-codes/) or [M49 region code](https://unstats.un.org/unsd/methodology/m49/).
      format: ppaas_common_language_v3
      maxLength: 10
      minLength: 2
      pattern: "^[a-z]{2}(?:-[A-Z][a-z]{3})?(?:-(?:[A-Z]{2}|[0-9]{3}))?$"
    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
    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"
    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"
    token_attributes: {}
    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
    metadata: {}
    payment_token_request:
      title: Payment Token Request
      description: Payment Token Request where the `source` defines the type of instrument to be stored.
      type: object
      properties:
        customer:
          description: Customer in merchant's or partner's system of records.
          "$ref": "#/components/schemas/customer"
        payment_source:
          title: Payment source request
          description: The payment method to vault with the instrument details.
          type: object
          properties:
            card:
              "$ref": "#/components/schemas/card_request"
            token:
              "$ref": "#/components/schemas/token_id_request"
        metadata:
          "$ref": "#/components/schemas/metadata"
      required:
        - payment_source
    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"
    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"
    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
    ordinal:
      type: integer
      description: Ordinal number for sorting.
      minimum: 1
      maximum: 99
    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
    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"
  parameters:
    paypal_request_id:
      name: PayPal-Request-Id
      description: The server stores keys for 3 hours.
      in: header
      required: true
      schema:
        type: string
    customer_id:
      name: customer_id
      description: A unique identifier representing a specific customer in merchant's/partner's system or records.
      in: query
      required: true
      schema:
        type: string
        minLength: 7
        maxLength: 36
        pattern: "^[0-9a-zA-Z_-]+$"
    page_size:
      name: page_size
      description: A non-negative, non-zero integer indicating the maximum number of results to return at one time.
      in: query
      required: false
      schema:
        type: integer
        minimum: 1
        default: 5
    page:
      name: page
      description: A non-negative, non-zero integer representing the page of the results.
      in: query
      required: false
      schema:
        type: integer
        minimum: 1
        default: 1
    total_required:
      name: total_required
      description: A boolean indicating total number of items (total_items) and pages (total_pages) are expected to be returned in the response.
      in: query
      required: false
      schema:
        type: boolean
        default: false
    id:
      name: id
      description: ID of the setup token.
      in: path
      required: true
      schema:
        type: string
        minLength: 7
        maxLength: 36
        pattern: "^[0-9a-zA-Z_-]+$"