Charging for services
A service is something your business bills for: a subscription, a SMS bundle, a delivery fee. Charging a customer for it debits their wallet and credits the service's own account, so your revenue per service is always on the books.
How services work
You create services in the back office under Services. Each has a unique code, a currency and a pricing type:
- Flat: a fixed price. Every charge uses it. You can leave
amountout of the request, or send exactly the fixed price. Any other amount is rejected with422. - Dynamic: no fixed price. Every charge must include its own
amount.
List services
GET/service
Returns the active services your key can charge for, so your system can discover codes and prices.
{
"status": "OK",
"message": "Successful",
"Services": [
{
"_id": "665f1c2e9a3b4c0012ab3400",
"name": "Monthly plan",
"code": "PLAN",
"currency": "NGN",
"pricingType": "flat",
"amount": 5000,
"description": "Pro plan"
},
{
"_id": "665f1c2e9a3b4c0012ab3401",
"name": "SMS bundle",
"code": "SMS",
"currency": "NGN",
"pricingType": "dynamic",
"description": "Pay per bundle"
}
]
}curl -X GET "https://usetreasurywire.com/api/v1/service" \
-H "Authorization: Bearer $TREASURYWIRE_KEY"Charge a customer
POST/service/charge
Debits the customer's wallet and posts the amount to the service's account in one atomic step. The customer's wallet is found by customerRef in the service's currency.
| Body | Type | Description |
|---|---|---|
serviceCoderequired | string | The service's code, such as SMS. |
customerRefrequired | string | The customer's ownerRef. Their wallet is debited. |
referencerequired | string | Your idempotency reference, up to 100 characters, unique per service. |
amount | number | Major units, greater than 0. Required for a dynamic service. For a flat service, leave it out or send exactly its price. |
description | string | Shown on the customer's statement. |
{
"message": "Successful",
"status": "OK",
"reference": "inv_20260604_17",
"transactionId": "665f2a0b9a3b4c0012ab3501",
"ServiceCharge": {
"serviceCode": "SMS",
"customerRef": "cust_1001",
"reference": "inv_20260604_17",
"amount": 120000,
"currency": "NGN",
"description": "June SMS bundle"
}
}| Status | Meaning |
|---|---|
201 | The customer was charged. |
200 | This reference was already charged. Nothing moved this time. |
404 | No such service, or the customer has no wallet in the service's currency. |
409 | This reference was already used for a different customer or amount. |
422 | Insufficient balance, the service is inactive, the amount is missing (dynamic) or doesn't match the fixed price (flat). |
curl -X POST "https://usetreasurywire.com/api/v1/service/charge" \
-H "Authorization: Bearer $TREASURYWIRE_KEY" \
-H "Content-Type: application/json" \
-d '{
"serviceCode": "SMS",
"customerRef": "cust_1001",
"reference": "inv_20260604_17",
"amount": 1200,
"description": "June SMS bundle"
}'Reverse a charge
POST/service/charge/reverse
Refunds a charge using the reference it was made with. The amount is credited back to the customer's wallet and debited from the service's account. The original charge is never edited; a separate reversal entry is posted.
| Body | Type | Description |
|---|---|---|
serviceCoderequired | string | The service's code, such as SMS. |
referencerequired | string | The reference the charge was made with. |
{
"message": "Service charge reversed",
"status": "OK",
"reference": "inv_20260604_17",
"transactionId": "665f2b4c9a3b4c0012ab3620",
"ServiceCharge": {
"serviceCode": "SMS",
"customerRef": "cust_1001",
"reference": "inv_20260604_17",
"amount": 120000,
"currency": "NGN"
}
}| Status | Meaning |
|---|---|
201 | The charge was reversed and the customer refunded. |
200 | This charge was already reversed. Nothing moved this time. |
404 | No such service, or no charge was made with this reference. |
422 | The charge can't be reversed in its current status. |
curl -X POST "https://usetreasurywire.com/api/v1/service/charge/reverse" \
-H "Authorization: Bearer $TREASURYWIRE_KEY" \
-H "Content-Type: application/json" \
-d '{
"serviceCode": "SMS",
"reference": "inv_20260604_17"
}'