DOCSEARCHbyAlgolia
Submit Docs

Meridian Documentation

website·Indexed 30 days ago

https://meridian-docs.netlify.app

Payment infrastructure for collecting payments, managing recurring subscriptions, and handling payouts. Features include the PaymentIntent object for payment lifecycles, Meridian Radar for fraud detection, date-based API versioning, and a robust webhook system with retry logic and dead-letter queues. Supports one-off invoices, proration, and global compliance certifications.

Tokens
30.8K
Snippets
195
Records
284
Agent score
72%

What's inside Meridian

  1. Overview of the Meridian payment flow

    The standard payment process follows these steps:

    1. Customer initiates payment.
    2. Your server creates a PaymentIntent and returns a client_secret to the browser.
    3. Meridian.js uses the secret to confirm the payment.
    4. Meridian notifies your server via a webhook.
    5. Your server fulfills the order.

  2. Understand asynchronous webhook delivery in v2.4

    v2-4-release
    Meridian v2.4 transitioned webhook processing to be fully asynchronous. Webhooks are now dispatched independently, meaning a slow endpoint will no longer cause delivery delays for other webhooks in the same account. This change reduces average latency by ~40ms for high-volume accounts and requires no changes to existing endpoints or integrations.

  3. Understand how Meridian webhooks work

    Meridian webhooks notify your application in real time when specific events occur (e.g., payment success, subscription renewal). The process follows these steps: 1. You register an HTTPS endpoint. 2. Meridian sends a POST request to that URL when a matching event fires. 3. Your server processes the event and must return an HTTP 200 response. 4. If a 200 is not received, Meridian retries with exponential backoff.
    Meridian API  →  POST /your-webhook-endpoint
                  { "type": "payment_intent.succeeded", "data": { ... } }
Your Server   →  200 OK

  4. Understand the Meridian Event object structure

    Every action in a Meridian account generates an Event object, which serves as the source of truth for webhook payloads. Events are stored for 30 days. The object contains metadata about the event type, the underlying data object that triggered the event, request details, and timestamps.
    {
  "id": "evt_1NqX2B4eHqLMHCmD",
  "object": "event",
  "type": "payment_intent.succeeded",
  "data": {
    "object": {
      "id": "pi_3NqX2B4eHqLMHCmD",
      "object": "payment_intent",
      "amount": 2000,
      "status": "succeeded"
    }
  },
  "request": {
    "id": "req_8Xn1A4qZpKvTm2",
    "idempotency_key": null
  },
  "created": 1748476800,
  "livemode": false,
  "pending_webhooks": 0
}

  5. Understand Meridian Radar fraud detection and risk levels

    Meridian Radar is a built-in fraud detection engine that evaluates every payment in real time. It assigns a risk score from 0 to 100 based on signals including Card BIN data, IP address, device fingerprint, geolocation, velocity (frequency of attempts), historical network patterns, and custom rules.

    Risk levels are categorized as follows:

    • Normal (0–64): Default action is Allow.
    • Elevated (65–84): Default action is Allow, but the transaction is flagged for review.
    • Highest (85–100): Default action is Block.

  6. The Refund object schema

    The Refund object represents a return of funds to a customer's original payment method. It contains details about the amount, currency, associated charge or payment intent, the reason for the refund, and the current status.
    {
  "id": "re_3NqX2B4eHqLMHCmD",
  "object": "refund",
  "amount": 2000,
  "currency": "usd",
  "charge": "ch_3NqX2B4eHqLMHCmD",
  "payment_intent": "pi_3NqX2B4eHqLMHCmD",
  "reason": "customer_request",
  "status": "succeeded",
  "created": 1748476800
}

  7. Simulate time passage with Test Clocks

    v2-3-release
    Test Clocks allow developers to simulate the passage of time in test mode, enabling the testing of time-dependent billing logic without waiting for real-time intervals to elapse.

  8. Understand the Meridian payment infrastructure

    Meridian acts as a payment infrastructure layer between an application and the global financial system. It abstracts the complexity of authorization, fraud scoring, currency conversion, and settlement, providing a single API to interact with various banks and card networks.
    Your Application
       ↓  API call
  Meridian API
       ↓  routes to
  Card Networks (Visa, Mastercard, Amex)
       ↓  authorizes with
  Customer's Issuing Bank
       ↓  settles to
  Your Bank Account

  9. The Subscription object schema

    The Subscription object represents a customer's subscription to a plan. It contains details about the customer, the current billing period, the status of the subscription, and the associated line items.
    {
  "id": "sub_1NqX2B4eHqLMHCmD",
  "object": "subscription",
  "customer": "cus_Nk3mHXq7ViGwMz",
  "status": "active",
  "current_period_start": 1748476800,
  "current_period_end": 1751068800,
  "cancel_at_period_end": false,
  "items": {
    "object": "list",
    "data": [{ "id": "si_ItemId", "price": { "id": "price_ProMonthly", "unit_amount": 4900 } }]
  },
  "latest_invoice": "in_InvoiceId",
  "created": 1748476800,
  "livemode": false
}

  10. Understand the Meridian dispute and chargeback lifecycle

    A dispute (chargeback) occurs when a customer contests a charge via their bank. The process follows these steps:

    1. Customer disputes the charge.
    2. The bank provisionally reverses funds into a dispute reserve.
    3. Meridian sends a charge.dispute.created webhook notification.
    4. The merchant typically has 7–10 calendar days to submit evidence.
    5. The bank reviews the case (taking 60–90 days) and makes a final decision.
    6. If the merchant wins, funds are returned; otherwise, they are permanently withheld.

    Note: A non-refundable dispute fee of $15 is charged by Meridian regardless of the outcome.

  11. Understand the PaymentIntent object and its lifecycle

    A PaymentIntent tracks the lifecycle of a payment attempt from creation to confirmation and capture. It automatically handles edge cases like authentication, retries, and failures. The object contains key fields such as id, amount (in smallest currency unit), currency, status, customer, and a client_secret used for frontend confirmation.
    {
  "id": "pi_3NqX2B4eHqLMHCmD1vC8aKtz",
  "object": "payment_intent",
  "amount": 2000,
  "currency": "usd",
  "status": "succeeded",
  "customer": "cus_Nk3mHXq7ViGwMz",
  "description": "Pro plan – monthly",
  "client_secret": "pi_3NqX2B4eHqLMHCmD1vC8aKtz_secret_...",
  "payment_method": "pm_1NqX2B4eHqLMHCmD...",
  "livemode": false,
  "metadata": {},
  "created": 1748476800
}

  12. Understand the Meridian subscription model

    Meridian subscriptions enable recurring charges on monthly, annual, or custom intervals. A subscription is formed by linking three core objects: a Product (the offering), a Price (the cost, currency, and interval), and a Customer (the entity being charged). Meridian automatically manages invoicing, payment retries, dunning, and cancellations.