Switchain Services

Appearance

Payment Runs in Switchain ​

What is a Payment Run? ​

A payment run is an automated process that aggregates multiple outstanding dues (such as affiliate or partner commissions) and executes their payment in cryptocurrency. It streamlines the settlement of multiple debts into a single transaction, ensuring efficiency and accuracy in payouts.

Technical Details ​

Database Collections ​

  • Payment Runs:
    Stored in the Paymentruns collection/table.
  • Dues:
    Stored in the Dues collection/table.
  • Trades:
    Stored in the Trades collection/table.
  • Transfers:
    Stored in the Transfers collection/table.

Main Fields in Paymentruns ​

  • _id: Unique identifier.
  • appId: Reference to the partner/app.
  • kind: Type of payment run (e.g., affiliate).
  • rates: Exchange rates used for calculation.
  • status: Current status (created, rated, withdrawing, paid, etc.).
  • payoutInfo: Recipient address and details.
  • transferId: Transfers executed for payout.
  • createdAt, ratedAt: Timestamps.

Payment Run Workflow ​

1. Initiation ​

  • Partner Action:
    Partner clicks "Start Payment Run" on the dashboard.
  • Backend Trigger:
    Calls the Meteor method 'paymentrun.initOne', which creates a new document in Paymentruns.

2. Rate Calculation ​

  • System fetches current rates and calculates payout totals.
  • Rates are stored in the rates field of the payment run.

3. Payment Run Creation ​

  • Payment run document is created in Paymentruns.
  • References dues from Dues collection.

4. Supervision and Validation ​

  • Status changes to rated.
  • Validates payout info and user authentication.

5. Execution ​

  • Status changes to withdrawing.
  • Trades are created in Trades collection if conversion is needed.
  • Transfers are created in Transfers collection for the payout.

6. Completion ​

  • Status changes to paid once all transfers are confirmed.
  • Associated dues in Dues are marked as paid.

Payment Run Status Flow ​

A payment run in Switchain transitions through several statuses, each representing a step in the payout process.
Below is a detailed description of each status, how it changes, and who or what triggers the transition:

Statuses and Transitions ​

  1. created

    • How: Set automatically when the payment run is created (by the partner via dashboard).
    • Who: Partner action triggers backend method 'paymentrun.initOne'.
    • What: Payment run is initialized with selected open dues.

  2. rated

    • How: The system fetches current exchange rates and calculates payout totals.
    • Who: Backend logic, often triggered automatically after creation or by a partner/admin action (e.g., confirming payout details).
    • What: Rates are stored, payout amount is determined, and payout info is validated.

  3. withdrawing

    • How: Once rates and payout info are confirmed, the system initiates trades and transfers.
    • Who: Backend logic, typically triggered by a partner confirming the payout or by an admin supervising the process.
    • What: Trades are executed if asset conversion is needed, and transfers are created to send funds.

  4. paid

    • How: Set when all transfers are confirmed as completed on the blockchain or payment network.
    • Who: Backend logic, monitoring transfer confirmations.
    • What: Payment run is finalized, dues are marked as paid.

Who Triggers Each Transition? ​

  • Partner:
    Initiates the payment run and may confirm payout details.
  • Backend System:
    Handles rate calculation, trade execution, transfer creation, and monitors for completion.
  • Admin:
    Can supervise, manually advance, or resolve payment runs stuck in error states.

Error Handling and Manual Actions ​

  • If an error occurs (e.g., insufficient funds, invalid payout info, rate fluctuation), the payment run may enter a special error state or require manual intervention.
  • Admins have tools to review, retry, or cancel payment runs as needed.

Automated Jobs in the Payment Run Flow ​

While partners manually initiate payment runs, the progression of payment runs through their various statuses (created, rated, withdrawing, paid) is managed by automated jobs in the backend.

  • What do jobs do?

    • Periodically review payment runs in the database.
    • Automatically update their status as conditions are met (e.g., rates available, transfers confirmed).
    • Execute trades and transfers when required.
    • Handle error states and notify admins if manual intervention is needed.

  • Why are jobs important?

    • Ensure payment runs progress without manual supervision.
    • Provide reliability and automation for the payout process.

Technical Implementation: paymentrunsHelpers.js ​

The file admin/imports/api/paymentruns/server/paymentrunsHelpers.js contains the core backend logic for automating the payment run workflow after initiation.

Key Responsibilities ​

  • Supervision of Payment Runs:
    The supervise function is called by automated jobs to monitor and advance payment runs through their statuses (rated, withdrawing, paid).

  • Trade and Transfer Management:
    Functions like createPaymentrunTradesV2, monitorAndCloseTradesV2, createPayoutTransfer, and monitorPayoutTransfer handle the creation, monitoring, and completion of trades and transfers required for payouts.

  • Status Updates:
    The payment run status is updated in the database as each step is completed (e.g., after trades are closed or transfers are confirmed).

  • Error Handling:
    The helpers include checks for missing funds, stale rates, invalid addresses, and other edge cases, ensuring robust error management and logging.

Example Flow ​

  1. Job calls supervise with a payment run ID.
  2. Depending on the current status:
    • If rated, it validates payout info and moves to withdrawing.
    • If withdrawing, it creates trades, monitors their closure, creates transfers, and monitors their confirmation.
    • When all transfers are confirmed, the status is set to paid and dues are marked as paid.

This file is central to the automation and reliability of the payment run process in Switchain.

Special Cases & Error Handling ​

  • Insufficient Funds:
    Payment run fails if funds are insufficient.
  • Invalid Payout Info:
    Payment run is halted until info is corrected.
  • Rate Fluctuations:
    May require re-approval or recalculation.
  • Already Paid Dues:
    Excluded from the payment run.
  • Manual Intervention:
    Admins can resolve stuck payment runs.

Who Can Create a Payment Run? ​

  • Partners:
    Manually from their dashboard.

Where Are Payment Runs Used? ​

  • Partner Dashboard:
    View, initiate, and track payment runs.
  • Admin Panel:
    Supervise and resolve payment runs.

Benefits of Payment Runs ​

  • Efficiency:
    Multiple dues settled in one transaction.
  • Accuracy:
    Automated calculations.
  • Transparency:
    Status and details visible.
  • Security:
    Validation before transfers.

Summary ​

Payment runs are a core mechanism in Switchain for automating and managing the payout of accumulated dues.
Partners initiate payment runs, which are tracked and processed through the Paymentruns, Dues, Trades, and Transfers collections, ensuring secure and transparent payouts.
The status flow and error handling provide reliability and flexibility for both partners and admins throughout the payout process.