Money-Out Merchant Integration Guide

This guide outlines the process for implementing a Money-Out merchant integration with the Pillars platform. It provides technical instructions, API references, and data specifications for handling payment batch processing.

Authentication

To authenticate Pillars requests, we recommend using token-based headers rather than IP whitelisting, as Pillars services are hosted in Azure and static IPs are not guaranteed.

Token Authentication

Pillars will send the following headers in each request:

x-callbacktoken: The authentication token you must validate.
x-callbackexpire: The expiration time of the callback token in ISO 8601 format.

You must validate the x-callbacktoken before proceeding.

Token Validation Endpoint:

GET /Authentication/token/{token}

Reference: https://pillars-hub.readme.io/reference/get_authentication-token-token

A valid token will return HTTP 200 OK
An invalid token will return HTTP 401 Unauthorized

Batch Request Format

Pillars sends a batch of payment releases in the following JSON format:

{
  "id": "string",
  "releases": [
    {
      "bonusId": "string",
      "nodeId": "string",
      "currency": "string",
      "batchId": "string",
      "amount": 0,
      "detailId": 0,
      "periodId": 0,
      "status": 0
    }
  ]
}

Field Definitions

Field	Description
`id`	Unique identifier for the entire batch. If a failed batch is retried, this ID will remain the same.
`batchId`	Matches the top-level `id`. Always identical.
`bonusId`	ID of the bonus being paid (e.g., "ULB Level 1"). Defined in each compensation plan.
`nodeId`	Identifier for the customer receiving the payment.
`currency`	Typically follows ISO 4217 format (e.g., "USD", "EUR"). Admins can define custom codes, so validation should be flexible.
`amount`	Decimal value representing the payment amount (e.g., `1563.12`).
`detailId`	Unique identifier for the combination of `nodeId` and `bonusId`.
`periodId`	ID representing the compensation period in Pillars.
`status`	Integer indicating status (0 = pending). Use corresponding string in the response.

Customer Details Lookup

To retrieve customer information (e.g., name, email), use the customer lookup endpoint. This is useful for large batches to fetch user data in smaller groups.

Endpoint:

GET /api/v1/Customers?ids={id1}&ids={id2}

Reference: https://pillars-hub.readme.io/reference/get_api-v1-customers

Accepts a list of customer Ids
Returns customer metadata

Period Details Lookup

To retrieve details for a given periodId, use the following endpoint:

Endpoint:

GET /api/v1/CompensationPlans/0/Periods/{PeriodId}

Reference: https://pillars-hub.readme.io/reference/get_api-v1-compensationplans-compensationplanid-periods-periodid

Response Handling

After processing a batch, send back the full list of releases to confirm their processing status.

Endpoint:

PUT /api/v1/batches/{id}

Reference: https://pillars-hub.readme.io/reference/put_api-v1-batches-id

Status Values (Response)

Code	Response String
0	Pending
1	Success
2	Failure

Note: While Pillars sends status as an integer, your response must use the corresponding string.

Sample Response

[
  {
    "bonusId": "Cust_Bon1",
    "nodeId": "N10",
    "currency": "USD",
    "batchId": "ABC123",
    "amount": 354.22,
    "detailId": 50302,
    "periodId": 234,
    "status": "Success"
  },
  {
    "bonusId": "Cust_Bon2",
    "nodeId": "N11",
    "currency": "USD",
    "batchId": "ABC123",
    "amount": 5003.92,
    "detailId": 85821,
    "periodId": 234,
    "status": "Failure"
  }
]

Best Practices

Validate the x-callbacktoken before any processing.
Use x-callbackexpire to manage expiration and prevent token reuse.
Always return the full object for each release when sending status updates.
Use the provided customer and period endpoints for additional data if required.
Prepare for batches of up to 500,000 payments.
Handle retries by checking for duplicate batch ids.
Safely ignore unknown currency codes by treating them as failures.

Additional Resources

For questions or further assistance, please contact the Pillars development team.