API005 - Mass Pay API (Batch Transfer) – Technical Overview

Executive Summary

The Mass Pay API allows your application to disburse funds to multiple recipients in a single HTTP request. Designed with a Wallet-First architecture, this asynchronous API ensures funds are securely routed to a recipient’s wallet or through to external rails (Banks, Cards, etc.), ensuring zero fund loss during provider failure.

1. How It Works (The Lifecycle)

The API operates asynchronously to handle high volumes efficiently.

1. Submit: Your system POSTs a batch of transactions.

2. Validation: We perform a lightweight synchronous check (schema, format, auth) and immediately return a 202 Accepted

3. Processing: We process items in the background (checking bank accounts, executing external transfers)

4. Notification: We send Webhooks to your system as items transition to Success or Failed

2. Integration Fundamentals

3. Key Developer Features

A. Wallet-First Reliability (No "Lost" Funds)

Unlike traditional fire-and-forget APIs, our system routes funds to a recipient wallet first.

• Happy Path: Funds credit the wallet -> Funds push to destination (e.g., Bank) -> Item marked Success.

• Provider Failure: If the external bank/provider declines the transfer, the funds are not reversed or lost. The item state becomes RetainedInWallet. The money sits safely in the recipient's wallet, ready for a retry or manual cashout

B. Smart Defaults & Auto-Creation

You do not need to manage complex wallet logic on your end.

• Auto-Create: If a recipient doesn't have a wallet, we auto-create one in the batch currency.

• Smart Routing: If you omit specific destination IDs (like WalletId), we automatically select the recipient's default wallet or bank account.

C. Bring Your Own IDs (Idempotency)

You can supply your own CustomerBatchId and CustomerTransactionId for easy reconciliation with your internal ledgers.

• IDs are echoed back in all responses and webhooks.

• If you omit them, we generate high-entropy, collision-resistant IDs for you.

4. Supported Payment Methods

The API supports mixed-method batches. You define the method via SendMethodId.

• Bank Transfer (XTR94500): Direct-to-bank. Supports fallback to the recipient's default bank if BeneficiaryBankID is omitted.

• Wallets (XTR94502/04): Transfer to Individual or Company wallets.

• Cards: Prepaid Virtual Debit Cards (XTR94503) and Digital Gift Cards (XTR94505).

• Rapid Transfer (XTR94508): Push-to-card functionality.

• Physical Check (XTR94507): Mailed checks (US Only).

5. Observability & Status Checks

You are never in the dark about a payment's status.

• Real-Time Webhooks: We emit events for Batch.Started, Batch.Item.Completed, and Batch.Item.Failed. All payloads include the specific ErrorCode if a failure occurs.

  • Action Required: To enable these notifications, you must provide a destination URL endpoint to your Account Manager, Customer Success Manager, or by emailing support@xtrm.com.

• Status Endpoint: Call GET /API/v4/Fund/BatchTransfer/{BatchId} to see the aggregate status of a batch or drill down into specific items.

• History: You can retrieve a full attempt history (audit trail) for every transaction to see timestamps and results of retries.

6. Quick FAQ for Engineering

• What if I send a duplicate request?

  • If you reuse a CustomerTransactionId within the same batch, we flag it immediately. If you reuse it across batches, we return a 409 Conflict to prevent double-spending.

• How do I handle errors?

  • If you reuse a CustomerTransactionId within the same batch, we flag it immediately. If you reuse it across batches, we return a 409 Conflict to prevent double-spending.

• How do I handle errors?

  • We provide a closed catalog of error codes (e.g., INSUFFICIENT_FUNDS_RUNTIME, RECIPIENT_NOT_FOUND) so you can programmatically react to failures.

• Can I retry a failed item?

  • Yes. You can resubmit the batch with the same IDs. If an item failed previously, we create a new AttemptNo (preserving the history). If it succeeded previously, we return ALREADY_COMPLETED.