API006 - Mass Pay API Implementation Guide

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 and 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

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

Item object schema

Each object within the Items array:

Supported send methods and destination fields

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

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": "recipient@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 apisupport@xtrm.com.

Security: signature verification

Every request includes the X-Signature header: t=, v1=.

Verification steps:

1. Extract t (timestamp) and v1 (signature).

2. Construct the base string: t + "." + RawRequestBody (bytes).

3. Compute HMAC-SHA256 using your secret.

4. Compare your hash to v1.

Event types and 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 the X-Event-Id header to deduplicate events.

7. Common error codes