openapi: 3.0.3
info:
  title: Ravelin Merchant 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
tags:
- name: Checkout
  description: Pre-payment order risk scoring.
- name: Transactions
  description: Payment attempts, captures, refunds, and authorizations.
- name: Customer
  description: Customer profile, identity, and label events.
- name: Authentication
  description: Login and registration events for account takeover scoring.
- name: Vouchers
  description: Voucher, promo, and payment-method voucher events.
- name: Supplier
  description: Supplier, driver, courier, and seller events for marketplace risk.
- name: Disputes
  description: Chargebacks, disputes, and reclaim events.
- name: Refunds
  description: Refund requests and decisioning.
- name: Payouts
  description: Outbound payouts to suppliers and recipients.
- name: Connect
  description: Cross-merchant identity and signal sharing.
paths:
  /v2/checkout:
    post:
      tags: [Checkout]
      summary: Score a Checkout Event
      operationId: createCheckout
      description: Submit an order at checkout to receive a real-time risk decision before payment is
        captured. Recommended as the primary pre-payment integration point.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CheckoutRequest'
      responses:
        '200':
          description: Risk decision returned successfully.
          content:
            application/json:
              schema: { $ref: '#/components/schemas/DecisionResponse' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '429': { $ref: '#/components/responses/RateLimited' }
  /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' }
  /v2/refund:
    post:
      tags: [Refunds]
      summary: Submit a Refund Request
      operationId: createRefund
      description: Submit a refund request for risk scoring against refund-abuse models. Returns an
        action recommending whether to grant the refund.
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/RefundRequest' }
      responses:
        '200': { $ref: '#/components/responses/Decision' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '429': { $ref: '#/components/responses/RateLimited' }
  /v2/dispute:
    post:
      tags: [Disputes]
      summary: Submit a Dispute
      operationId: createDispute
      description: Notify Ravelin of an issuer-initiated dispute or chargeback so it can feed back into
        ML training and link analysis.
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/DisputeRequest' }
      responses:
        '200': { $ref: '#/components/responses/Decision' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '429': { $ref: '#/components/responses/RateLimited' }
  /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' }
  /v3/login:
    post:
      tags: [Authentication]
      summary: Score a Login Event
      operationId: createLoginV3
      description: Submit a login attempt (successful or failed) for account takeover scoring. Supports
        password, social, OTP, U2F, RSA, SMS, magic link, reCAPTCHA, biometric, and push authentication
        mechanisms.
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/LoginRequest' }
      responses:
        '200': { $ref: '#/components/responses/Decision' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '429': { $ref: '#/components/responses/RateLimited' }
  /v2/registration:
    post:
      tags: [Authentication]
      summary: Score a Registration Event
      operationId: createRegistration
      description: Score a new customer or supplier registration event for fake-account, breach-credential,
        and onboarding-fraud risk.
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/RegistrationRequest' }
      responses:
        '200': { $ref: '#/components/responses/Decision' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '429': { $ref: '#/components/responses/RateLimited' }
  /v2/reclaim:
    post:
      tags: [Disputes]
      summary: Submit a Reclaim Event
      operationId: createReclaim
      description: Submit a customer reclaim or goodwill credit event for refund and policy-abuse
        scoring.
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/ReclaimRequest' }
      responses:
        '200': { $ref: '#/components/responses/Decision' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '429': { $ref: '#/components/responses/RateLimited' }
  /v2/voucher:
    post:
      tags: [Vouchers]
      summary: Submit a Voucher Redemption
      operationId: createVoucher
      description: Submit a voucher, promo code, or loyalty redemption event for promo-abuse scoring.
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/VoucherRequest' }
      responses:
        '200': { $ref: '#/components/responses/Decision' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '429': { $ref: '#/components/responses/RateLimited' }
  /v2/voucher-check:
    post:
      tags: [Vouchers]
      summary: Pre-Check a Voucher Redemption
      operationId: createVoucherCheck
      description: Pre-flight risk check on a voucher redemption attempt before granting the voucher
        value.
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/VoucherRequest' }
      responses:
        '200': { $ref: '#/components/responses/Decision' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '429': { $ref: '#/components/responses/RateLimited' }
  /v2/payment-method-voucher:
    post:
      tags: [Vouchers]
      summary: Submit a Payment-Method Voucher Event
      operationId: createPaymentMethodVoucher
      description: Submit a voucher event linked to a specific payment method (e.g. card-linked
        offers) for risk scoring.
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/VoucherRequest' }
      responses:
        '200': { $ref: '#/components/responses/Decision' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '429': { $ref: '#/components/responses/RateLimited' }
  /v2/supplier:
    post:
      tags: [Supplier]
      summary: Submit a Supplier Event
      operationId: createSupplier
      description: Submit a supplier, driver, courier, restaurant, shop, or seller profile event for
        marketplace risk scoring.
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/SupplierRequest' }
      responses:
        '200': { $ref: '#/components/responses/Decision' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '429': { $ref: '#/components/responses/RateLimited' }
  /v2/supplier-label:
    post:
      tags: [Supplier]
      summary: Apply a Supplier Label
      operationId: createSupplierLabel
      description: Apply or remove a fraud / trust label on a supplier to feed back into ML training.
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/SupplierLabelRequest' }
      responses:
        '200': { $ref: '#/components/responses/Decision' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '429': { $ref: '#/components/responses/RateLimited' }
  /v2/payout:
    post:
      tags: [Payouts]
      summary: Submit a Payout Event
      operationId: createPayout
      description: Submit an outbound payout event (to a supplier, marketplace seller, or recipient)
        for risk scoring.
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/PayoutRequest' }
      responses:
        '200': { $ref: '#/components/responses/Decision' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '429': { $ref: '#/components/responses/RateLimited' }
  /v2/connect:
    post:
      tags: [Connect]
      summary: Submit a Connect Event
      operationId: createConnect
      description: Submit a Ravelin Connect event for cross-merchant identity and signal sharing across
        the consortium.
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/ConnectRequest' }
      responses:
        '200': { $ref: '#/components/responses/Decision' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '429': { $ref: '#/components/responses/RateLimited' }
components:
  securitySchemes:
    secretApiKey:
      type: apiKey
      in: header
      name: Authorization
      description: 'Secret API key prefixed with the literal word `token`, e.g. `Authorization: token sk_live_...`.'
  responses:
    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' }
    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' }
  schemas:
    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 }
    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 }
    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 }
    Order:
      type: object
      required: [orderId, creationTime, price, currency]
      properties:
        orderId: { type: string }
        creationTime: { type: integer, format: int64 }
        price: { type: integer, description: 'Total price in the currency''s basic units.' }
        currency: { type: string, description: 'ISO 4217 currency code.' }
        country: { type: string }
        note: { type: string, maxLength: 4000 }
        to: { type: object }
        suppliers: { type: array, items: { type: object } }
    PaymentMethod:
      type: object
      properties:
        methodType: { type: string, description: 'card | wallet | bank | paypal | cash | other' }
        instrumentId: { type: string }
        bin: { type: string }
        last4: { type: string }
    CheckoutRequest:
      type: object
      required: [timestamp, order]
      properties:
        timestamp: { type: integer, format: int64 }
        eventType: { type: string }
        customerId: { type: string }
        customer: { $ref: '#/components/schemas/Customer' }
        order: { $ref: '#/components/schemas/Order' }
        paymentMethods:
          type: array
          items: { $ref: '#/components/schemas/PaymentMethod' }
        device: { $ref: '#/components/schemas/Device' }
    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' }
    PaymentMethodRequest:
      type: object
      required: [timestamp, customerId, paymentMethod]
      properties:
        timestamp: { type: integer, format: int64 }
        customerId: { type: string }
        paymentMethod: { $ref: '#/components/schemas/PaymentMethod' }
    RefundRequest:
      type: object
      required: [timestamp, orderId]
      properties:
        timestamp: { type: integer, format: int64 }
        orderId: { type: string }
        customerId: { type: string }
        refund:
          type: object
          properties:
            refundId: { type: string }
            amount: { type: integer }
            currency: { type: string }
            reason: { type: string }
    DisputeRequest:
      type: object
      required: [timestamp, orderId]
      properties:
        timestamp: { type: integer, format: int64 }
        orderId: { type: string }
        customerId: { type: string }
        dispute:
          type: object
          properties:
            disputeId: { type: string }
            amount: { type: integer }
            currency: { type: string }
            reasonCode: { type: string }
            status: { type: string }
    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 }
    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 }
    LoginRequest:
      type: object
      required: [timestamp, login]
      properties:
        timestamp: { type: integer, format: int64 }
        login:
          type: object
          required: [username, success]
          properties:
            username: { type: string }
            success: { type: boolean }
            authenticationMechanism:
              type: object
              description: 'At least one of password, social, oneTimeCode, u2f, rsaKey, smsCode,
                magicLink, captcha, biometric, push.'
            app:
              type: object
              properties:
                name: { type: string }
                platform: { type: string }
                domain: { type: string }
        device: { $ref: '#/components/schemas/Device' }
    RegistrationRequest:
      type: object
      required: [timestamp, registration]
      properties:
        timestamp: { type: integer, format: int64 }
        registration:
          type: object
          properties:
            app:
              type: object
              properties:
                name: { type: string }
                platform: { type: string }
                domain: { type: string }
            registrationMechanism:
              type: object
              description: 'password | social | oneTimeCode | captcha | biometric.'
        customer: { $ref: '#/components/schemas/Customer' }
        supplier:
          type: object
          properties:
            supplierId: { type: string }
            type: { type: string, enum: [driver, courier, restaurant, shop, seller, other] }
            email: { type: string }
            name: { type: string }
            telephone: { type: string }
            groupId: { type: string }
            groupName: { type: string }
            registrationTime: { type: integer, format: int64 }
        device: { $ref: '#/components/schemas/Device' }
    ReclaimRequest:
      type: object
      required: [timestamp, orderId]
      properties:
        timestamp: { type: integer, format: int64 }
        orderId: { type: string }
        customerId: { type: string }
        reclaim:
          type: object
          properties:
            reclaimId: { type: string }
            amount: { type: integer }
            currency: { type: string }
            reason: { type: string }
    VoucherRequest:
      type: object
      required: [timestamp, voucher]
      properties:
        timestamp: { type: integer, format: int64 }
        customerId: { type: string }
        voucher:
          type: object
          properties:
            voucherId: { type: string }
            code: { type: string }
            value: { type: integer }
            currency: { type: string }
            redeemedTime: { type: integer, format: int64 }
    SupplierRequest:
      type: object
      required: [timestamp, supplier]
      properties:
        timestamp: { type: integer, format: int64 }
        supplier:
          type: object
          properties:
            supplierId: { type: string }
            type: { type: string }
            email: { type: string }
            name: { type: string }
            telephone: { type: string }
            registrationTime: { type: integer, format: int64 }
        device: { $ref: '#/components/schemas/Device' }
    SupplierLabelRequest:
      type: object
      required: [timestamp, supplierId, label]
      properties:
        timestamp: { type: integer, format: int64 }
        supplierId: { type: string }
        label:
          type: object
          properties:
            value: { type: string, enum: [FRAUDULENT, TRUSTED, UNKNOWN] }
            note: { type: string }
    PayoutRequest:
      type: object
      required: [timestamp, payout]
      properties:
        timestamp: { type: integer, format: int64 }
        payout:
          type: object
          properties:
            payoutId: { type: string }
            recipientId: { type: string }
            amount: { type: integer }
            currency: { type: string }
            method: { type: string }
    ConnectRequest:
      type: object
      required: [timestamp]
      properties:
        timestamp: { type: integer, format: int64 }
        customerId: { type: string }
        signals:
          type: array
          items: { type: object }
security:
- secretApiKey: []