API006 - Mass Pay API Implementation Guide

Modified on Wed, 18 Feb at 12:25 PM

1. Introduction

The Mass Pay API allows you to disburse funds to multiple recipients in a single HTTP request.

Key Concepts:

Asynchronous Processing: You submit a batch and receive a 202 Accepted immediately. Processing happens in the background .
Observability: Status is tracked via polling (GET) or pushed via Webhooks.

2. Authentication & Base Setup

Authentication: Bearer Token (OAuth2 / API Key) scoped to the Issuer Account.
Transport: TLS 1.2+ Required.
Content-Type: application/json (UTF-8).

3. Creating a Batch (The API Call)

Endpoint

POST /API/v4/Fund/BatchTransfer

Request Body Schema

Field	Type	Required	Description
IssuerAccountNumber	String	Yes	The account that owns the source funds.
SourceWalletId	String	Yes	The wallet funding the batch. Implies the currency.
CustomerBatchId	String	No	Client-supplied ID (unique). If omitted, server assigns one.
EmailNotification	Boolean	No	Optional flag for email delivery rails.
Items	Array	Yes	List of transactions (Max 1,000 default).

The request consists of a batch "envelope" containing an array of transaction items.Item Object Schema

Each object within the Items array:

Field	Type	Required	Description
CustomerTransactionId	String	No	Client-supplied unique ID. If omitted, server assigns one.
RecipientId	String	Yes	Unique identifier for the recipient.
SendMethodId	String	Yes	The method ID (see table below).
Amount	String	Yes	Positive decimal string (e.g., "125.50").
Description	String	No	Optional note (max 1024 chars).
Destination	Object	Yes	Object containing method-specific fields (Bank ID, Email, etc.).

Supported Send Methods & Destination Fields

You must provide the correct Destination fields based on the SendMethodId .

Method	ID	Required Destination Fields
Bank Transfer	XTR94500	BeneficiaryBankID (Optional - defaults to wallet's default bank if omitted)
Wallet	XTR94502	WalletId (Optional - defaults to recipient's default wallet)
Prepaid Debit Card	XTR94503	Email, SKU
Digital Gift Card	XTR94505	Email, SKU
Rapid Transfer	XTR94508	CardToken
Check (US Only)	XTR94507	BeneficiaryCheckAddress, City, State, PostalCode, CountryCodeISO2, Name

Example Request

JSON

{

"IssuerAccountNumber": "ACC-884920",

"SourceWalletId": "WAL-99281",

"CustomerBatchId": "BATCH-2024-10-01",

"Items": [

{

"CustomerTransactionId": "TRX-001",

"RecipientId": "USR-5510",

"SendMethodId": "XTR94500",

"Amount": "150.00",

"Destination": {

"BeneficiaryBankID": "BNK-1120"

}

{

"RecipientId": "USR-5511",

"SendMethodId": "XTR94505",

"Amount": "50.00",

"Destination": {

"Email": "user@example.com",

"SKU": "SKU-AMAZON-USD"

}

]

}

4. Responses

Success (202 Accepted)

Returned if at least one item passes synchronous validation. Valid items are enqueued; invalid items are rejected immediately .

JSON

{

"CustomerBatchId": "BATCH-2024-10-01",

"Status": "Processing",

"AcceptedCount": 1,

"ReceivedCount": 2,

"Accepted": [

{

"CustomerTransactionId": "TRX-001",

"RecipientId": "USR-5510",

"Status": "Processing"

}

"Rejected": [

{

"CustomerTransactionId": "ct_generated_xyz",

"ErrorCode": "INVALID_FIELD",

"Field": "Items[1].Destination.SKU",

"Message": "SKU not found"

}

]

}

Failure (422 Unprocessable Entity)

Returned if zero items pass validation or if envelope fields (e.g., SourceWalletId) are missing.

5. Status Retrieval (GET)

To check the status of a batch or specific item if you aren't using webhooks.

Batch Status

GET /API/v4/Fund/BatchTransfer/{CustomerBatchId}

Returns Status: Processing | Completed | CompletedWithFailures | Failed.
Includes a summary count of items and an item map.

Item Status

GET /API/v4/Fund/BatchTransfer/{CustomerBatchId}/Items/{CustomerTransactionId}

Returns detailed status (Success, RetainedInWallet, Failed).
Optional: Add query param ?History=true to see the full audit trail of attempts.

6. Webhook Integration

Webhooks provide real-time updates. You must verify them to ensure security.

Endpoint Registration

Action Required: Provide your HTTPS webhook receiver URL to your Account Manager or email support@xtrm.com.

Security: Signature Verification

Every request includes the X-Signature header: t=<timestamp>, v1=<signature> .

Verification Steps:

Extract t (timestamp) and v1 (signature).
Construct the base string: t + . + RawRequestBody (bytes).
Compute HMAC-SHA256 using your Secret.
Compare your hash to v1.

Event Types & Payloads

1. Batch.Item.Completed

Triggered when a transaction succeeds.

Note: Check DeliveryType. If DeliveryType: "Wallet", the external transfer failed but funds are safely stored in the user's wallet .

JSON

{

"CustomerBatchId": "BATCH-2024-10-01",

"CustomerTransactionId": "TRX-001",

"Status": "Success",

"Amount": "150.00",

"Currency": "USD",

"RecipientId": "USR-5510",

"DeliveryType": "Bank",

"AttemptNo": 1

}

2. Batch.Item.Failed

Triggered when a transaction fails permanently.

JSON

{

"CustomerBatchId": "BATCH-2024-10-01",

"CustomerTransactionId": "TRX-002",

"Status": "Failed",

"ErrorCode": "RECIPIENT_NOT_FOUND",

"AttemptNo": 1

}

3. Batch.Completed

Triggered when all items in the batch have reached a final state.

JSON

{

"CustomerBatchId": "BATCH-2024-10-01",

"BatchStatus": "CompletedWithFailures",

"Succeeded": 1,

"Failed": 1,

"CompletedAt": "2025-08-21T16:46:00Z"

}

Retry Policy

Timeout: Respond with 200 OK within 5 seconds.
Retries: If you fail to respond, the system retries with exponential backoff for ~24 hours.
Idempotency: Use X-Event-Id header to deduplicate events.

7. Common Error Codes

Code	Context	Meaning
INVALID_FIELD	Validation	Missing field or invalid format (e.g., negative amount).
RECIPIENT_NOT_FOUND	Runtime	The RecipientId does not exist.
INSUFFICIENT_FUNDS_RUNTIME	Runtime	Source wallet lacks funds at moment of execution.
CURRENCY_MISMATCH	Runtime	Gift card SKU or wallet currency does not match batch.
DUPLICATE_ITEM_IN_REQUEST	Sync	Same CustomerTransactionId used twice in one request.