List Merchants
GET /merchants
Retrieve a list of all merchants associated with your company and their current balances.
Authentication
Requires a Secret Key (sk_...) in the x-api-key header or as a Bearer token in the Authorization header.
Example Request
curl https://api.taprails.com/api/v1/management/merchants \
-H "x-api-key: sk_live_your_key"
Response
The response is a JSON object containing an array of merchant objects.
| Field | Type | Description |
|---|
merchants | array | A list of merchant objects. |
Merchant Object
| Field | Type | Description |
|---|
id | string | Unique identifier for the merchant (e.g., mch_abc123). |
name | string | The merchant’s name. |
email | string | The merchant’s contact email. |
wallet_address | string | The USDC wallet address provisioned for this merchant on Base. |
balance | string | Current USDC balance of the merchant’s wallet. |
created_at | string | ISO 8601 timestamp of when the merchant was created. |
Sample Response
{
"merchants": [
{
"id": "mch_abc123",
"name": "Coffee Haven",
"email": "owner@coffeehaven.com",
"wallet_address": "0x742d35Cc6634C0532925a3b844Bc454e4438f44e",
"balance": "150.50",
"created_at": "2026-03-28T22:33:53Z"
},
{
"id": "mch_def456",
"name": "The Juice Bar",
"email": "billing@juicebar.io",
"wallet_address": "0x1234567890abcdef1234567890abcdef12345678",
"balance": "85.20",
"created_at": "2026-03-29T10:15:00Z"
}
]
}
Create Merchant
POST /merchants/create
Creates a new merchant under your company and provisions a dedicated Privy embedded wallet for their funds.
Request Body
| Field | Type | Required | Description |
|---|
name | string | Yes | The merchant’s legal or trade name (min 2 chars). |
email | string | Yes | Unique contact email for the merchant. |
Example Request
curl -X POST https://api.taprails.com/api/v1/management/merchants/create \
-H "x-api-key: sk_live_your_key" \
-H "Content-Type: application/json" \
-d '{
"name": "Urban Eats",
"email": "ops@urbaneats.com"
}'
Response
| Field | Type | Description |
|---|
merchant | object | The newly created merchant object. |
Merchant Object (Create)
| Field | Type | Description |
|---|
id | string | Unique identifier for the merchant. |
name | string | The merchant’s name. |
email | string | The merchant’s email. |
wallet_address | string | The provisioned USDC wallet address. |
privy_user_id | string | The underlying Privy user ID for the merchant’s wallet. |
balance | string | Initial balance (typically “0.00”). |
environment | string | The environment (test or live). |
created_at | string | ISO 8601 timestamp. |
Sample Response
{
"merchant": {
"id": "mch_xyz789",
"name": "Urban Eats",
"email": "ops@urbaneats.com",
"wallet_address": "0xabcdef1234567890abcdef1234567890abcdef",
"privy_user_id": "did:privy:ckxyz789...",
"balance": "0.00",
"environment": "live",
"created_at": "2026-03-31T01:15:00Z"
}
}
Errors
| Status | Code | Description |
|---|
| 400 | VALIDATION_ERROR | Name too short or invalid email format. |
| 400 | DUPLICATE_RESOURCE | A merchant with this email already exists. |
| 401 | UNAUTHORIZED | Invalid or missing Secret Key. |
Merchant Ledger
GET /merchants/:id/transactions
Retrieve the complete financial history for a specific merchant, including atomic balance snapshots for every transaction. Useful for auditing and deep financial reconciliation.
Query Parameters
| Parameter | Type | Required | Description |
|---|
limit | number | No | Number of records to return (default 50, max 100). |
Example Request
curl https://api.taprails.com/api/v1/management/merchants/mch_xyz789/transactions?limit=25 \
-H "x-api-key: sk_live_your_key"
Sample Response
{
"merchant_id": "mch_xyz789",
"merchant_name": "Urban Eats",
"total_count": 1,
"transactions": [
{
"id": "tx_abc123",
"type": "PAYMENT",
"amount": "5.00",
"balance_before": "100.00",
"balance_after": "105.00",
"payment_id": "pay_987654",
"status": "COMPLETED",
"description": "NFC Payment Received",
"created_at": "2026-04-03T12:00:00Z"
}
]
}
Update Status
PATCH /merchants/:id/status
Pause or reactivate a merchant’s ability to process payments. This is a self-service toggle for companies to manage their sub-merchants.
Request Body
| Field | Type | Required | Description |
|---|
status | string | Yes | The new status. Allowed: ACTIVE, PAUSED. |
Example Request
curl -X PATCH https://api.taprails.com/api/v1/management/merchants/mch_xyz789/status \
-H "x-api-key: sk_live_your_key" \
-H "Content-Type: application/json" \
-d '{
"status": "PAUSED"
}'
Sample Response
{
"id": "mch_xyz789",
"name": "Urban Eats",
"status": "PAUSED",
"updated_at": "2026-04-04T15:00:00Z"
}
Platform Restrictions: If a merchant has been set to BLACKLISTED, FROZEN, or SUSPENDED by the TapRails platform (e.g. for compliance or security reasons), you cannot override that status using this endpoint. You will receive a 403 Forbidden error.
