Ravelin 3D Secure API

openapi: 3.2.0
info:
  title: Ravelin Server 3D Secure API
  version: '1'
  description: Ravelin's PSP-agnostic, PCI 3DS-validated 3D Secure Server API.
  contact:
    name: Ravelin Support
    url: https://support.ravelin.com/
  termsOfService: https://www.ravelin.com/legal/terms-of-service
  license:
    name: Proprietary
servers:
- url: https://3ds.live.pci.ravelin.com
  description: PCI 3DS production endpoint
security:
- secretApiKey: []
tags:
- name: 3D Secure
  description: EMV 3DS 2.x authentication operations.
paths:
  /3ds/version:
    post:
      tags:
      - 3D Secure
      summary: Look Up 3DS Version for a Card
      operationId: lookup3dsVersion
      description: Look up the available 3DS protocol versions for a given card. Used before initiating an Authentication Request to determine the supported 3DS Method URL and protocol version.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - timestamp
              properties:
                timestamp:
                  type: integer
                  format: int64
                pan:
                  type: string
                paymentMethod:
                  type: object
                  description: Encrypted payment method payload.
      responses:
        '200':
          description: Version lookup result.
          content:
            application/json:
              schema:
                type: object
                properties:
                  threeDSServerTransID:
                    type: string
                  acsStartProtocolVersion:
                    type: string
                  acsEndProtocolVersion:
                    type: string
                  dsStartProtocolVersion:
                    type: string
                  dsEndProtocolVersion:
                    type: string
                  threeDSMethodURL:
                    type: string
                    format: uri
  /3ds/authenticate:
    post:
      tags:
      - 3D Secure
      summary: Send a 3DS Authentication Request (AReq)
      operationId: authenticate3ds
      description: Send transaction, merchant, and cardholder data to the 3DS Server to initiate an Authentication Request (AReq). Returns the transStatus and, when applicable, the data needed to proceed to a challenge.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AuthenticateRequest'
      responses:
        '200':
          description: AReq result.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuthenticateResponse'
  /3ds/challenge:
    post:
      tags:
      - 3D Secure
      summary: Send a 3DS Challenge Request
      operationId: challenge3ds
      description: Submit the Challenge Request when the AReq returned transStatus=C, completing the cardholder challenge flow (OTP, biometric, etc.).
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - timestamp
              - acsTransID
              - threeDSServerTransID
              properties:
                timestamp:
                  type: integer
                  format: int64
                acsTransID:
                  type: string
                threeDSServerTransID:
                  type: string
      responses:
        '200':
          description: Challenge response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuthenticateResponse'
  /3ds/result:
    post:
      tags:
      - 3D Secure
      summary: Retrieve a 3DS Authentication Result
      operationId: result3ds
      description: Retrieve the final authentication result by 3DS Server Transaction ID after a Challenge has completed.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - timestamp
              - threeDSServerTransID
              properties:
                timestamp:
                  type: integer
                  format: int64
                threeDSServerTransID:
                  type: string
      responses:
        '200':
          description: Authentication result.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuthenticateResponse'
components:
  schemas:
    AuthenticateResponse:
      type: object
      properties:
        transStatus:
          type: string
          enum:
          - Y
          - A
          - N
          - U
          - C
          - D
          - R
          - I
          - S
          description: 'Authentication outcome. Y=Authenticated, A=Attempted, N=Not authenticated,

            U=Authentication unavailable, C=Challenge required, D=Challenge required (decoupled),

            R=Rejected, I=Informational only, S=Challenge using cardholder-facing service.

            '
        authenticationValue:
          type: string
          description: CAVV / AAV / AEVV verification value, base64 encoded.
        acsTransID:
          type: string
        threeDSServerTransID:
          type: string
        eci:
          type: string
        liabilityShifted:
          type: boolean
        acsURL:
          type: string
          format: uri
        cReq:
          type: string
          description: Base64 Challenge Request payload, when transStatus=C.
    AuthenticateRequest:
      type: object
      required:
      - timestamp
      - areqData
      properties:
        timestamp:
          type: integer
          format: int64
        pan:
          type: string
          description: Unencrypted PAN, when not using an encrypted paymentMethod.
        paymentMethod:
          type: object
          description: Encrypted payment method payload.
        areqData:
          type: object
          required:
          - messageCategory
          - deviceChannel
          - threeDSRequestorID
          - threeDSRequestorName
          - threeDSRequestorURL
          properties:
            messageCategory:
              type: string
              enum:
              - '01'
              - '02'
              description: 01 = Payment Authentication, 02 = Non-Payment Authentication.
            deviceChannel:
              type: string
              enum:
              - '01'
              - '02'
              - '03'
              description: 01 = APP, 02 = BRW, 03 = 3RI.
            threeDSRequestorID:
              type: string
            threeDSRequestorName:
              type: string
            threeDSRequestorURL:
              type: string
              format: uri
            purchaseAmount:
              type: string
            purchaseCurrency:
              type: string
            purchaseExponent:
              type: string
            purchaseDate:
              type: string
            acquirerMerchantID:
              type: string
            acquirerBIN:
              type: string
            merchantName:
              type: string
            merchantCountryCode:
              type: string
            mcc:
              type: string
  securitySchemes:
    secretApiKey:
      type: apiKey
      in: header
      name: Authorization
      description: Secret API key prefixed with `token`.