Ravelin 3D Secure API

openapi: 3.0.3
info:
  title: Ravelin Server 3D Secure API
  version: '1'
  description: 'Ravelin''s PSP-agnostic, PCI 3DS-validated 3D Secure Server API. Implements EMV 3DS 2.x

    Authentication Request (AReq), Challenge, Result, and Version Lookup operations against

    3ds.live.pci.ravelin.com. Supports both encrypted payment method payloads and unencrypted

    PAN, dynamic exemption routing, and card-scheme-specific authentication values (CAVV, AAV,

    AEVV). Integrates with the Ravelin iOS, Android, and browser SDKs for App-based (APP),

    Browser-based (BRW), and 3RI (3DS Requestor Initiated) channels.


    Endpoint documentation: https://developer.ravelin.com/merchant/api/endpoints/3d-secure/.

    '
  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`.