openapi: 3.0.0
info:
  title: Push Provisioning API (⚠️ Work in Progress)
  description: >-
    This API is intended for card issuers who want to provide a fast, secure,
    and user-friendly way for customers

    to add (push) their eligible cards to Vipps or MobilePay without manually
    entering card details.


    ### Authentication

    Mutual TLS authentication for secure API communication.

    To access this API, you must provide a valid client certificate signed by
    Vipps MobilePay Certificate Authority.


    Vipps MobilePay Certificate Authority details:

    - root certificate: https://certs.godaddy.com/repository/gdroot-g2.crt

    - intermediate certificate :
    https://certs.godaddy.com/repository/gdig2.crt.pem
  contact:
    name: Vipps MobilePay
    url: https://vipps.no
    email: support_ps@vippsmobilepay.com
  version: 0.1.0
servers:
  - url: https://provisioning.vipps.no
    description: Production server
  - url: https://provisioning-mt.vipps.no
    description: Sandbox server
paths:
  /api/issuer/provisioning/push/card/v1:
    post:
      summary: Initiate Card Provisioning
      description: >-
        Initiate card provisioning flow to let the user easily add the given
        card to their Vipps MobilePay app.
      operationId: PaymentSourcesFeaturesProvisioningPushIssuerCardEndpoint
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Request'
        required: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Response'
        '400':
          description: Bad Request - The request was invalid or cannot be served.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '500':
          description: >-
            Internal Server Error - An error occurred while processing the
            request.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
components:
  schemas:
    ProblemDetails:
      type: object
      properties:
        type:
          type: string
          description: A URI reference that identifies the problem type.
          example: https://tools.ietf.org/html/rfc7231#section-6.5.1
        title:
          type: string
          description: A short, human-readable summary of the problem type.
          example: Validation Error
        status:
          type: integer
          description: The HTTP status code.
          format: int32
          example: 400
        detail:
          type: string
          description: >-
            A human-readable explanation specific to this occurrence of the
            problem.
          nullable: true
          example: One or more validation errors occurred.
        traceId:
          type: string
          description: Trace identifier for the request.
          nullable: true
          example: 0HNH8TOC2B99B:00000001
        instance:
          type: string
          description: >-
            A URI reference that identifies the specific occurrence of the
            problem.
          nullable: true
          example: /api/v1/example
        errors:
          type: object
          additionalProperties:
            type: array
            items:
              type: string
          description: Validation errors organized by field name.
          nullable: true
      description: >-
        A machine-readable format for specifying errors in HTTP API responses
        based on RFC 7807.
    Request:
      required:
        - encryptedCardData
        - countryCode
        - nin
        - returnUrl
        - appSwitch
        - last4
      type: object
      properties:
        encryptedCardData:
          type: string
          description: >-
            Encrypted JSON Web Encryption (JWE) token containing sensitive card
            data.

            - Required headers: alg, enc, kid.

            - Algorithm: RSA-OAEP-256 with SHA-256 key and 4096-bit size.

            - Encryption: AES-128-GCM with 128-bit key.

            - Pan: Payment Account Reference (PAN) of the card e.g.
            1234567890123456.

            - Expiry: Card expiration date in YYYY-MM format, e.g. '2025-12'.

            - Payload: { pan, expiry }.
          example: eyJhbGciOiJSU0EtT0FFUC0yNTYiLCJlbmMiOiJBMjU2R0NNIn0...
        countryCode:
          type: string
          description: >-
            ISO 3166-1 alpha-2 country code for the cardholder's issuing
            country.
          example: 'NO'
        nin:
          type: string
          description: National identity number of the cardholder.
          example: '12345678901'
        returnUrl:
          type: string
          description: >-
            Redirect URL for returning to the calling application after
            provisioning completes.
          example: https://example.com/callback
        appSwitch:
          type: boolean
          description: >-
            Indicates whether the issuer is calling from a mobile device that
            may have the Vipps MobilePay app installed.
          example: true
        last4:
          type: string
          description: >-
            Last 4 digits of the card number for display and verification
            purposes.
          example: '1234'
    Response:
      type: object
      properties:
        url:
          type: string
          description: >-
            Deep link URL for switching to the Vipps MobilePay app and
            initiating the provisioning flow.
          format: uri
          example: >-
            https://qr-test.vipps.no/payment-sources/provisioning/push/card?session-id=f9e8d7c6-b5a4-3210-fedc-ba0987654321
