TreasuryWireAPI docsSign inGet API keys

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 amount out of the request, or send exactly the fixed price. Any other amount is rejected with 422.
  • 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.

Response
{
  "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.

BodyTypeDescription
serviceCoderequiredstringThe service's code, such as SMS.
customerRefrequiredstringThe customer's ownerRef. Their wallet is debited.
referencerequiredstringYour idempotency reference, up to 100 characters, unique per service.
amountnumberMajor units, greater than 0. Required for a dynamic service. For a flat service, leave it out or send exactly its price.
descriptionstringShown on the customer's statement.
201 Created
{
  "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"
  }
}
StatusMeaning
201The customer was charged.
200This reference was already charged. Nothing moved this time.
404No such service, or the customer has no wallet in the service's currency.
409This reference was already used for a different customer or amount.
422Insufficient 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.

BodyTypeDescription
serviceCoderequiredstringThe service's code, such as SMS.
referencerequiredstringThe reference the charge was made with.
201 Created
{
  "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"
  }
}
StatusMeaning
201The charge was reversed and the customer refunded.
200This charge was already reversed. Nothing moved this time.
404No such service, or no charge was made with this reference.
422The 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"
  }'