openapi: 3.0.3
info:
  title: Ravelin Server 3D Secure Customer 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: Customer
  description: Customer profile, identity, and label events.
paths:
  /v2/customer:
    post:
      tags:
      - Customer
      summary: Submit a Customer Profile
      operationId: createCustomer
      description: Submit or update a customer profile (identity, contact, account type, location, device) for risk scoring outside of an order context.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CustomerRequest'
      responses:
        '200':
          $ref: '#/components/responses/Decision'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/RateLimited'
  /v2/customer-label:
    post:
      tags:
      - Customer
      summary: Apply a Customer Label
      operationId: createCustomerLabel
      description: Apply or remove a fraud / trust label on a customer, e.g. to mark a customer as FRAUDULENT after a confirmed chargeback. Labels feed back into ML training.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CustomerLabelRequest'
      responses:
        '200':
          $ref: '#/components/responses/Decision'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/RateLimited'
components:
  responses:
    RateLimited:
      description: Per-merchant rate limit exceeded. Ravelin retains and processes the data after the limit clears, but the response is a 429.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Decision:
      description: Risk decision returned successfully.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/DecisionResponse'
    Unauthorized:
      description: Invalid or missing API key.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  schemas:
    CustomerLabelRequest:
      type: object
      required:
      - timestamp
      - customerId
      - label
      properties:
        timestamp:
          type: integer
          format: int64
        customerId:
          type: string
        label:
          type: object
          properties:
            value:
              type: string
              enum:
              - FRAUDULENT
              - TRUSTED
              - UNKNOWN
            note:
              type: string
            reviewer:
              type: string
    Customer:
      type: object
      properties:
        customerId:
          type: string
          maxLength: 300
        email:
          type: string
          format: email
        registrationTime:
          type: integer
          format: int64
        emailVerifiedTime:
          type: integer
          format: int64
        name:
          type: string
        familyName:
          type: string
        givenName:
          type: string
        telephone:
          type: string
          description: E.164 format preferred.
        telephoneVerifiedTime:
          type: integer
          format: int64
        accountType:
          type: string
          enum:
          - GUEST
          - REGISTERED
        location:
          type: object
          properties:
            country:
              type: string
            postalCode:
              type: string
            street:
              type: string
            city:
              type: string
            region:
              type: string
    Error:
      type: object
      properties:
        status:
          type: integer
        timestamp:
          type: integer
          format: int64
        message:
          type: string
    Device:
      type: object
      properties:
        deviceId:
          type: string
        ipAddress:
          type: string
        userAgent:
          type: string
        language:
          type: string
        location:
          type: object
    CustomerRequest:
      type: object
      required:
      - timestamp
      - customer
      properties:
        timestamp:
          type: integer
          format: int64
        customer:
          $ref: '#/components/schemas/Customer'
        device:
          $ref: '#/components/schemas/Device'
        custom:
          type: object
    DecisionResponse:
      type: object
      properties:
        status:
          type: integer
          description: HTTP status code echoed in the body.
        timestamp:
          type: integer
          format: int64
          description: Unix timestamp in milliseconds for when the decision was finalized.
        message:
          type: string
          description: Error description, if any.
        data:
          type: object
          properties:
            action:
              type: string
              enum:
              - ALLOW
              - REVIEW
              - PREVENT
              - PERMIT
              - WARN
              - BLOCK
              description: Recommended action. PERMIT / WARN / BLOCK are legacy aliases of ALLOW / REVIEW / PREVENT.
            source:
              type: string
              enum:
              - RAVELIN
              - RULE
              - LOOKUP
              - RATE_LIMIT
              description: Source of the recommendation.
            score:
              type: integer
              minimum: 0
              maximum: 100
              description: Fraud confidence score between 0 and 100.
            scoreId:
              type: string
              description: Unique identifier for this score, used to correlate the decision with downstream events.
            customerId:
              type: string
              description: Customer identifier echoed back from the request.
            rules:
              type: array
              items:
                type: object
                properties:
                  name:
                    type: string
                  state:
                    type: string
                    enum:
                    - active
                    - passive
                  description:
                    type: string
            warnings:
              type: array
              description: Data-quality warnings flagged on the input payload.
              items:
                type: object
  securitySchemes:
    secretApiKey:
      type: apiKey
      in: header
      name: Authorization
      description: Secret API key prefixed with `token`.