Ravelin Transactions API

openapi: 3.2.0
info:
  title: Ravelin Merchant Transactions API
  version: '2'
  description: 'The Ravelin Merchant API is the REST surface used by merchants to submit customer, order, login,

    registration, transaction, payment, voucher, supplier, dispute, refund, payout, and reclaim events

    to Ravelin and receive back a real-time risk decision. Each endpoint is POST-only, accepts a JSON

    payload, and returns a decision envelope containing the recommended `action` (ALLOW / REVIEW /

    PREVENT), the decision `source`, a 0-100 fraud `score`, a unique `scoreId`, the triggered `rules`,

    and any data-quality `warnings`.


    Authentication is via an `Authorization: token sk_live_...` (or `sk_test_...`) header. Per-merchant

    rate limits scale horizontally; a global per-customer rate limit of 50 events/minute is enforced

    and returns a 200 with `action=PREVENT` and `source=RATE_LIMIT`.


    Endpoints documented at https://developer.ravelin.com/merchant/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://api.ravelin.com
  description: Production
security:
- secretApiKey: []
tags:
- name: Transactions
  description: Payment attempts, captures, refunds, and authorizations.
paths:
  /v2/transaction:
    post:
      tags:
      - Transactions
      summary: Submit a Transaction Event
      operationId: createTransaction
      description: Submit a transaction attempt (auth, capture, auth_capture, refund, void, preauth) for scoring and to keep Ravelin's transaction history in sync with the merchant's PSP.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TransactionRequest'
      responses:
        '200':
          $ref: '#/components/responses/Decision'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/RateLimited'
  /v2/payment-method:
    post:
      tags:
      - Transactions
      summary: Submit a Payment Method
      operationId: createPaymentMethod
      description: Submit a payment method associated with a customer for tokenization, link analysis, and risk scoring.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PaymentMethodRequest'
      responses:
        '200':
          $ref: '#/components/responses/Decision'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/RateLimited'
components:
  schemas:
    PaymentMethod:
      type: object
      properties:
        methodType:
          type: string
          description: card | wallet | bank | paypal | cash | other
        instrumentId:
          type: string
        bin:
          type: string
        last4:
          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
    PaymentMethodRequest:
      type: object
      required:
      - timestamp
      - customerId
      - paymentMethod
      properties:
        timestamp:
          type: integer
          format: int64
        customerId:
          type: string
        paymentMethod:
          $ref: '#/components/schemas/PaymentMethod'
    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
    TransactionRequest:
      type: object
      required:
      - timestamp
      - orderId
      - customerId
      properties:
        timestamp:
          type: integer
          format: int64
        orderId:
          type: string
          maxLength: 300
        customerId:
          type: string
          maxLength: 300
        eventType:
          type: string
        paymentMethod:
          $ref: '#/components/schemas/PaymentMethod'
        transaction:
          type: object
          properties:
            transactionId:
              type: string
            time:
              type: integer
              format: int64
            amount:
              type: integer
            currency:
              type: string
            type:
              type: string
              enum:
              - auth
              - capture
              - auth_capture
              - refund
              - void
              - preauth
            success:
              type: boolean
            gateway:
              type: string
            gatewayReference:
              type: string
            declineCode:
              type: string
            authCode:
              type: string
            3ds:
              type: object
              properties:
                attempted:
                  type: boolean
                challenged:
                  type: boolean
                success:
                  type: boolean
                version:
                  type: string
                eci:
                  type: string
                liabilityShifted:
                  type: boolean
        device:
          $ref: '#/components/schemas/Device'
  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'
    Unauthorized:
      description: Invalid or missing API key.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Decision:
      description: Risk decision returned successfully.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/DecisionResponse'
  securitySchemes:
    secretApiKey:
      type: apiKey
      in: header
      name: Authorization
      description: 'Secret API key prefixed with the literal word `token`, e.g. `Authorization: token sk_live_...`.'