visa-digital-enablement.yml

openapi: 3.0.1
info:
  title: Visa Digital Enablement Lite App
  description: >-
    The Visa Digital Enablement (VDE) Lite App is a standalone, white-label
    solution that enables cardholders to push card credentials into Apple Pay
    (for iOS users) or Google Wallet (for Android users) without the need to
    download a client's mobile app. This efficient user experience facilitates
    quick and seamless execution of targeted tasks like provisioning to a
    digital wallet, thereby enabling immediate use of the card.
  version: '1'
servers:
  - url: https://sandbox.api.visa.com
    description: Sandbox server
security: []
tags:
  - name: URL Generation API
    description: URL Generation API
paths:
  /inapp/provision/appclip/url:
    post:
      tags:
        - URL Generation API
      summary: Generate VDE Lite app URL
      description: Create app clip or instant app URL for given payload.
      parameters:
        - $ref: '#/components/parameters/clientId'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateUrlRequest'
            examples:
              Card ID:
                summary: Card ID
                value:
                  emailLookupEnable: true
                  payload:
                    cardId: x123&
                    cardIdMetadata:
                      - clientId: C2
                      - customerId: C122
                    cardIdProvider: FWD
                    source: X123
                    user:
                      lastName: Doe
                      firstName: John
                      phoneNumber: '+13352226060'
                      locale: en-US
                      email: jdoe@visa.com
                  appId: d071aeff-9a39-c1b3-4482-1cbb9d300f01
              Using PAN:
                summary: Using PAN
                value:
                  emailLookupEnable: true
                  payload:
                    expirationYear: '2024'
                    nameOnAccount: John Doe
                    cardType: DEBIT
                    source: X123
                    billingAddress:
                      phoneNumber: '0015555551234'
                      city: Rocklin
                      countryCode: US
                      postalCode: '94404'
                      addressLine1: 933 Anvil Cir
                      addressLine2: Test
                      addressLine3: Street
                      stateProvinceCode: CA
                    expirationMonth: '11'
                    cardBrand: VISA
                    accountNumber: '4321432112341234'
                    user:
                      firstname: John
                      phoneNumber: '0015555551234'
                      locale: en-US
                      email: Jdoe@email.com
                      lastname: Doe
                  appId: d071aeff-9a39-c1b3-4482-1cbb9d300f01
        required: true
      responses:
        '201':
          description: Success Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateUrlResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BadRequestResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '503':
          description: Service Unavailable
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      x-operationVersions:
        - label: v1 - Latest
          operationPointer: '#/paths/~1inapp~1provision~1appclip~1url/post'
          default: false
      x-hideTryIt: true
components:
  schemas:
    BadRequestResponse:
      required:
        - httpStatus
        - message
        - reason
      type: object
      properties:
        reason:
          type: string
          description: Error Code for the error condition.
        message:
          type: string
          description: >-
            Message describing the error condition with additional information
            wherever applicable.
        requestId:
          type: string
          description: Request unix timestamp, for debugging purpose.
        httpStatus:
          type: string
          description: HTTP Status code
          example: '400'
        correlationId:
          type: string
          description: Request trace id, for debugging purpose.
        errorMessages:
          type: array
          items:
            type: object
            properties:
              message:
                type: string
                description: Detailed error message if any.
              location:
                type: string
                description: Detailed error location if any.
              attribute:
                type: string
                description: Detailed error attribute if any.
    CreateUrlRequest:
      required:
        - appId
      type: object
      properties:
        appId:
          type: string
          description: Issuer application Id.
          example: d071aeff-9a39-c1b3-4482-1cbb9d300f01
        payload:
          oneOf:
            - required:
                - accountNumber
                - cardBrand
                - cardType
                - expirationMonth
                - expirationYear
                - nameOnAccount
              type: object
              properties:
                user:
                  type: object
                  properties:
                    email:
                      type: string
                      description: >-
                        The users email address, which will be used to identify
                        the users existing account or user profile or to
                        establish a new account or user profile (e.g.
                        JOHNSMITH@email.com).
                    locale:
                      type: string
                      description: >-
                        Locale code (en-US)- It helps to identify the locale to
                        be selected for email notifications.
                    lastname:
                      type: string
                      description: The users Last Name (e.g. SMITH).
                    firstname:
                      type: string
                      description: The users First Name (e.g. JOHN).
                    phoneNumber:
                      type: string
                      description: >-
                        Cardholder phone number including country code, without
                        spaces and special characters (e.g. 0016503334444).
                source:
                  type: string
                  description: >-
                    Optional for Single-Use clients. Required for
                    Multi-Use/Channel Partner clients.
                cardType:
                  type: string
                  description: 'Valid values are: DEBIT, CREDIT, PREPAID.'
                cardBrand:
                  type: string
                  description: 'Valid values are: VISA, MC.'
                accountNumber:
                  type: string
                  description: Full card number.
                nameOnAccount:
                  type: string
                  description: Full name on the card (Must use UTF-8 characters).
                billingAddress:
                  required:
                    - addressLine1
                    - city
                    - countryCode
                    - phoneNumber
                    - postalCode
                    - stateProvinceCode
                  type: object
                  properties:
                    city:
                      maxLength: 100
                      type: string
                      description: >-
                        City of the billing address (e.g. New York), no special
                        characters.
                    postalCode:
                      type: string
                      description: >-
                        U.S.: 5-digit numeric value (e.g. 94100). Canada:
                        6-digit alphanumeric value (e.g. M4B1B3). Other
                        countries: 5-16 digit alphanumeric value without special
                        characters.
                    countryCode:
                      type: string
                      description: >-
                        Must be in ISO 3166-1 alpha-2 or ISO 3166-1 alpha-3 or
                        ISO 3-digit numeric format (Recommend ISO 3166-1 alpha-2
                        format, e.g. US).
                    phoneNumber:
                      type: string
                      description: >-
                        Cardholder phone number including country code, without
                        spaces and special characters (e.g. 0016503334444).
                    addressLine1:
                      maxLength: 256
                      type: string
                      description: >-
                        Line 1 of the billing address (Must use UTF-8
                        characters)
                    addressLine2:
                      maxLength: 256
                      type: string
                      description: >-
                        Line 2 of the address, which usually corresponds to
                        apartment, suite, etc. (Must use UTF-8 characters)
                    addressLine3:
                      maxLength: 256
                      type: string
                      description: Line 3 of the address (Must use UTF-8 characters)
                    stateProvinceCode:
                      type: string
                      description: >-
                        Must be in ISO 3166-2 format, alphabetic value with max
                        length of 3 characters, with no dashes or spaces.
                expirationYear:
                  type: string
                  description: Year when the card is set to expire (e.g. 2023).
                expirationMonth:
                  type: string
                  description: Month when the card is set to expire (e.g. 02 for Feb).
              description: With PAN info
            - required:
                - cardId
                - cardIdProvider
              type: object
              properties:
                user:
                  type: object
                  properties:
                    email:
                      type: string
                      description: >-
                        The users email address, which will be used to identify
                        the users existing account or user profile or to
                        establish a new account or user profile (e.g.
                        JOHNSMITH@email.com).
                    locale:
                      type: string
                      description: >-
                        Locale code (en-US)- It helps to identify the locale to
                        be selected for email notifications.
                    lastname:
                      type: string
                      description: The users Last Name (e.g. SMITH).
                    firstname:
                      type: string
                      description: The users First Name (e.g. JOHN).
                    phoneNumber:
                      type: string
                      description: >-
                        Cardholder phone number including country code, without
                        spaces and special characters (e.g. 0016503334444).
                cardId:
                  type: string
                  description: Card Identifier/Card ID.
                source:
                  type: string
                  description: >-
                    Optional for Single-Use clients. Required for
                    Multi-Use/Channel Partner clients.
                cardIdMetadata:
                  type: array
                  items:
                    type: object
                    properties:
                      clientId:
                        type: string
                        description: >-
                          Client information that can be used to resolve Card
                          ID. Information will be passed as-is to Card ID
                          provider. Conditional logic based on Card ID Provider:
                          FWD  Not Applicable; VUCE  Required; Issuer Client
                          ID value from VUCE API DCP Onboarding configuration
                          (Note: There are different values for Sandbox/CERT and
                          Production); VBR  Not Applicable.
                      customerId:
                        type: string
                        description: >-
                          Client information that can be used to resolve Card
                          ID. Information will be passed as-is to Card ID
                          provider who can resolve the card. Conditional logic
                          based on Card ID Provider: FWD  Not Applicable; VUCE
                           Required for Multi-Use/Channel Partners clients
                          (unless Client ID is provided); VBR  Not Applicable.
                cardIdProvider:
                  type: string
                  description: >-
                    Provider who can resolve the Card ID to the actual card
                    account data. Valid Values are: FWD, VUCE, VBR.
              description: With Card Id Request
        emailLookupEnable:
          type: boolean
          description: Enable search by email.
          example: true
    CreateUrlResponse:
      type: object
      properties:
        url:
          type: string
          description: URL generated
          example: https://domain.visa.com/dlink/push?payload=abc
        notified:
          type: boolean
          description: Notification status if enabled. By default
          example: false
    ErrorResponse:
      required:
        - httpStatus
        - message
        - reason
      type: object
      properties:
        reason:
          type: string
          description: Error Code for the error condition.
        message:
          type: string
          description: >-
            Message describing the error condition with additional information
            wherever applicable.
        requestId:
          type: string
          description: Request unix timestamp, for debugging purpose.
        httpStatus:
          type: string
          description: HTTP Status code
        correlationId:
          type: string
          description: Request trace id, for debugging purpose.
  responses: {}
  parameters:
    clientId:
      name: x-client-id
      in: header
      description: VDP client ID via Service Context
      required: true
      explode: false
      schema:
        type: string
      example: 86da0f74-19f0-4a20-9dde-3e83dfa6bf83
  examples: {}
  requestBodies: {}
  headers: {}
  callbacks: {}
x-tagGroups:
  - name: API Reference
    tags:
      - URL Generation API