API reference · Moving money

Bills

Airtime, data, power and TV: catalogue, account check, prepaid tokens, schedules. About bills Live

POST/billSave a bill
GET/bill/categoriesList bill categories
POST/bill/categoryCreate a bill category
GET/bill/category/{reference}Fetch a bill category
PUT/bill/category/{reference}Update a bill category
GET/bill/category/{reference}/providersList the billers in a category
POST/bill/paymentPay a bill
GET/bill/payment/{reference}Fetch a bill payment
POST/bill/payment/{reference}/resolveResolve a bill payment by hand
GET/bill/payments/reviewList bill payments awaiting manual review
GET/bill/productLook a product up by its biller and code
GET/bill/product/{reference}Fetch a product
PUT/bill/product/{reference}/overrideOverride a synced product's presentation
GET/bill/providerLook a biller up by its aggregator and code
GET/bill/provider/{reference}Fetch a biller
GET/bill/provider/{reference}/productsList a biller's products
POST/bill/scheduleSchedule a bill
GET/bill/schedule/{reference}Read one bill schedule
POST/bill/schedule/{reference}/cancelCancel a bill schedule
POST/bill/schedule/{reference}/pausePause a bill schedule
POST/bill/schedule/{reference}/resumeResume a bill schedule
POST/bill/schedule/{reference}/runRun a bill schedule now
GET/bill/schedule/{reference}/runsList a schedule's runs
GET/bill/schedulesList your bill schedules
POST/bill/validateValidate a customer identifier at the biller
GET/bill/{reference}Read one saved bill
GET/billsList your saved bills

POST Save a bill

POST /bill

Keeps a bill the customer expects to pay again - a meter, a smartcard, a policy, a subscription - so it can be paid by reference and, later, on a schedule. The account is validated with the biller before it is saved, and the name the biller holds for it comes back on the response. Show that name: a bill pointing at the wrong meter is otherwise discovered by paying a stranger's electricity. This is the same record a payment saves when asked to, so a bill created here and one kept from a completed payment are one thing. Provider, currency and category all follow from the product and are not accepted from the caller. For a product whose amount the customer chooses, amount keeps how much the bill is usually paid for; it must fall within the product's limits. A fixed-price product is always its own price. Supply schedule to start paying the bill on a schedule as it is saved. The schedule follows the same rules as POST /bill/schedule and needs a validated transaction PIN; it defaults to paying the bill's amount, and if it is refused the bill is not saved either.

Headers

Name	Notes
`Authorization`	Bearer token
`X-Tenant`	Your tenant
`X-Environment`	test or live
`Content-Type`	application/json

Example

Request body: BillRequest · Response: GenericResponseBillResponse

curl -X POST "https://api.bridgemoni.com/bill" \
  -H "Authorization: Bearer $BRIDGEMONI_TOKEN" \
  -H "X-Tenant: $BRIDGEMONI_TENANT" \
  -H "X-Environment: $BRIDGEMONI_ENV" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Ikeja Electric - Flat 3",
  "description": "Prepaid meter, upstairs flat. Landlord reimburses quarterly.",
  "productCode": "IKEDC_PREPAID",
  "accountNumber": 45012345678,
  "amount": 5000.0,
  "schedule": {
    "name": "Monthly electricity",
    "sourceAccountNumber": 1000000199,
    "amountMode": "FIXED",
    "fixedAmount": 5000.0,
    "maximumAmount": 25000.0,
    "frequency": "DAILY",
    "dayOfMonth": 5,
    "dayOfWeek": 3,
    "startsOn": "2026-10-01",
    "endsOn": "2027-10-01",
    "maximumOccurrences": 12
  }
}'

{
  "name": "Ikeja Electric - Flat 3",
  "description": "Prepaid meter, upstairs flat. Landlord reimburses quarterly.",
  "productCode": "IKEDC_PREPAID",
  "accountNumber": 45012345678,
  "amount": 5000.0,
  "schedule": {
    "name": "Monthly electricity",
    "sourceAccountNumber": 1000000199,
    "amountMode": "FIXED",
    "fixedAmount": 5000.0,
    "maximumAmount": 25000.0,
    "frequency": "DAILY",
    "dayOfMonth": 5,
    "dayOfWeek": 3,
    "startsOn": "2026-10-01",
    "endsOn": "2027-10-01",
    "maximumOccurrences": 12
  }
}

{
  "data": {
    "reference": "b3f1c2d4-5e6a-4b7c-8d9e-0f1a2b3c4d5e",
    "name": "Ikeja Electric - Flat 3",
    "description": "string",
    "accountNumber": "45012345678",
    "maskedAccountNumber": "*******5678",
    "accountName": "ADA OKAFOR",
    "accountNameConfirmedAt": "2026-09-25T10:00:00Z",
    "productCode": "IKEDC_PREPAID",
    "providerCode": "IKEDC",
    "providerName": "Ikeja Electric",
    "categoryCode": "ELECTRICITY",
    "categoryName": "Electricity",
    "currencyCode": "NGN",
    "status": "string",
    "creationDateTime": "2026-09-25T10:00:00Z",
    "amount": 5000.0,
    "schedule": {
      "reference": "b3f1c2d4-5e6a-4b7c-8d9e-0f1a2b3c4d5e",
      "billReference": "b3f1c2d4-5e6a-4b7c-8d9e-0f1a2b3c4d5e",
      "billName": {
        "name": "string"
      },
      "name": {
        "name": "string"
      },
      "sourceAccountNumber": "string",
      "amountMode": "FIXED",
      "fixedAmount": {
        "amount": "10000.00",
        "currencyCode": "NGN"
      },
      "maximumAmount": {
        "amount": "10000.00",
        "currencyCode": "NGN"
      },
      "currencyCode": "string",
      "frequency": "DAILY",
      "dayOfMonth": 0,
      "dayOfWeek": 0,
      "nextRunAt": "2026-09-25T10:00:00Z",
      "startAt": "2026-09-25T10:00:00Z",
      "endAt": "2026-09-25T10:00:00Z",
      "maximumOccurrences": 0,
      "occurrenceCount": 0,
      "status": "ACTIVE",
      "consecutiveFailureCount": 0,
      "lastFailureCode": "string",
      "lastRunAt": "2026-09-25T10:00:00Z",
      "lastRunOutcome": "string",
      "creationDateTime": "2026-09-25T10:00:00Z"
    }
  },
  "description": "Bill created successfully"
}

Responses

Status	When
`200`	Bill created successfully
`400`	Amount is not allowed for this product; Say how much the schedule should pay; That cadence is incomplete
`403`	Transaction PIN validation required
`404`	No such product in the catalogue
`409`	The biller could not confirm that account, or this bill is already saved

GET List bill categories

GET /bill/categories

Lists the available bill categories, optionally narrowed to a single country. The country is where the bill is paid, not where the payer is - a customer abroad paying a bill back home should pass the destination country, not their own.

Headers

Name	Notes
`Authorization`	Bearer token
`X-Tenant`	Your tenant
`X-Environment`	test or live

Query parameters

Name	Default
`countryCode`	Optional

Example

Response: List<BillCategoryResponse>

curl -X GET "https://api.bridgemoni.com/bill/categories?countryCode=value" \
  -H "Authorization: Bearer $BRIDGEMONI_TOKEN" \
  -H "X-Tenant: $BRIDGEMONI_TENANT" \
  -H "X-Environment: $BRIDGEMONI_ENV"

{
  "data": [
    {
      "reference": "b3f1c2d4-5e6a-4b7c-8d9e-0f1a2b3c4d5e",
      "code": "Ada Obi",
      "name": "Ada Obi",
      "categoryType": "AIRTIME",
      "countryCode": "NG",
      "description": "March payroll",
      "displayOrder": 1,
      "iconUrl": "Ada Obi",
      "active": true
    }
  ],
  "description": "List bill categories"
}

Responses

Status	When
`200`	Bill categories fetched successfully

POST Create a bill category

POST /bill/category

Creates a category that billers and their products are grouped under, such as electricity or cable television.

Headers

Name	Notes
`Authorization`	Bearer token
`X-Tenant`	Your tenant
`X-Environment`	test or live
`Content-Type`	application/json

Example

Request body: BillCategoryRequest · Response: BillCategoryResponse

curl -X POST "https://api.bridgemoni.com/bill/category" \
  -H "Authorization: Bearer $BRIDGEMONI_TOKEN" \
  -H "X-Tenant: $BRIDGEMONI_TENANT" \
  -H "X-Environment: $BRIDGEMONI_ENV" \
  -H "Content-Type: application/json" \
  -d '{
    "code": "Ada Obi",
    "name": "Ada Obi",
    "categoryType": "AIRTIME",
    "countryCode": "NG",
    "description": "March payroll",
    "displayOrder": 1,
    "iconUrl": "Ada Obi"
  }'

{
  "code": "Ada Obi",
  "name": "Ada Obi",
  "categoryType": "AIRTIME",
  "countryCode": "NG",
  "description": "March payroll",
  "displayOrder": 1,
  "iconUrl": "Ada Obi"
}

{
  "data": {
    "reference": "b3f1c2d4-5e6a-4b7c-8d9e-0f1a2b3c4d5e",
    "code": "Ada Obi",
    "name": "Ada Obi",
    "categoryType": "AIRTIME",
    "countryCode": "NG",
    "description": "March payroll",
    "displayOrder": 1,
    "iconUrl": "Ada Obi",
    "active": true
  },
  "description": "Create a bill category"
}

Responses

Status	When
`200`	Bill category created successfully
`409`	Bill category already registered

GET Fetch a bill category

GET /bill/category/{reference}

Fetches one bill category by reference.

Headers

Name	Notes
`Authorization`	Bearer token
`X-Tenant`	Your tenant
`X-Environment`	test or live

Path parameters

Name
`reference`

Example

Response: BillCategoryResponse

curl -X GET "https://api.bridgemoni.com/bill/category/b3f1c2d4-5e6a-4b7c-8d9e-0f1a2b3c4d5e" \
  -H "Authorization: Bearer $BRIDGEMONI_TOKEN" \
  -H "X-Tenant: $BRIDGEMONI_TENANT" \
  -H "X-Environment: $BRIDGEMONI_ENV"

{
  "data": {
    "reference": "b3f1c2d4-5e6a-4b7c-8d9e-0f1a2b3c4d5e",
    "code": "Ada Obi",
    "name": "Ada Obi",
    "categoryType": "AIRTIME",
    "countryCode": "NG",
    "description": "March payroll",
    "displayOrder": 1,
    "iconUrl": "Ada Obi",
    "active": true
  },
  "description": "Fetch a bill category"
}

Responses

Status	When
`200`	Bill category fetched successfully
`404`	Bill category not found

PUT Update a bill category

PUT /bill/category/{reference}

Updates a bill category's own attributes. Does not affect the providers or products beneath it.

Headers

Name	Notes
`Authorization`	Bearer token
`X-Tenant`	Your tenant
`X-Environment`	test or live
`Content-Type`	application/json

Path parameters

Name
`reference`

Example

Request body: UpdateBillCategoryRequest · Response: BillCategoryResponse

curl -X PUT "https://api.bridgemoni.com/bill/category/b3f1c2d4-5e6a-4b7c-8d9e-0f1a2b3c4d5e" \
  -H "Authorization: Bearer $BRIDGEMONI_TOKEN" \
  -H "X-Tenant: $BRIDGEMONI_TENANT" \
  -H "X-Environment: $BRIDGEMONI_ENV" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Ada Obi",
    "description": "March payroll",
    "displayOrder": 1,
    "iconUrl": "Ada Obi",
    "active": true
  }'

{
  "name": "Ada Obi",
  "description": "March payroll",
  "displayOrder": 1,
  "iconUrl": "Ada Obi",
  "active": true
}

{
  "data": {
    "reference": "b3f1c2d4-5e6a-4b7c-8d9e-0f1a2b3c4d5e",
    "code": "Ada Obi",
    "name": "Ada Obi",
    "categoryType": "AIRTIME",
    "countryCode": "NG",
    "description": "March payroll",
    "displayOrder": 1,
    "iconUrl": "Ada Obi",
    "active": true
  },
  "description": "Update a bill category"
}

Responses

Status	When
`200`	Bill category updated successfully
`404`	Bill category not found

GET List the billers in a category

GET /bill/category/{reference}/providers

Lists the providers available under a category - the billers a customer can pay.

Headers

Name	Notes
`Authorization`	Bearer token
`X-Tenant`	Your tenant
`X-Environment`	test or live

Path parameters

Name
`reference`

Example

Response: List<BillProviderResponse>

curl -X GET "https://api.bridgemoni.com/bill/category/b3f1c2d4-5e6a-4b7c-8d9e-0f1a2b3c4d5e/providers" \
  -H "Authorization: Bearer $BRIDGEMONI_TOKEN" \
  -H "X-Tenant: $BRIDGEMONI_TENANT" \
  -H "X-Environment: $BRIDGEMONI_ENV"

{
  "data": [
    {
      "reference": "b3f1c2d4-5e6a-4b7c-8d9e-0f1a2b3c4d5e",
      "providerCode": "provider code",
      "aggregatorCode": "Ada Obi",
      "name": "Ada Obi",
      "categoryReference": "b3f1c2d4-5e6a-4b7c-8d9e-0f1a2b3c4d5e",
      "countryCode": "NG",
      "currencyCode": "NGN",
      "status": "ACTIVE",
      "supportsValidation": true,
      "supportsRequery": true,
      "priority": 1
    }
  ],
  "description": "List the billers in a category"
}

Responses

Status	When
`200`	Bill providers fetched successfully

POST Pay a bill

POST /bill/payment

Submits a bill payment. A 200 does not always mean the biller was paid - check status. SUBMITTED and UNKNOWN both mean the outcome is still being confirmed and neither carries a token. Only SUCCESSFUL is a completed payment.

Headers

Name	Notes
`Authorization`	Bearer token
`X-Tenant`	Your tenant
`X-Environment`	test or live
`Idempotency-Key`	Reuse the same value on every retry of this request
`Content-Type`	application/json

Example

Request body: BillPaymentRequest · Response: BillPaymentResponse

curl -X POST "https://api.bridgemoni.com/bill/payment" \
  -H "Authorization: Bearer $BRIDGEMONI_TOKEN" \
  -H "X-Tenant: $BRIDGEMONI_TENANT" \
  -H "X-Environment: $BRIDGEMONI_ENV" \
  -H "Idempotency-Key: a-unique-key-per-intent" \
  -H "Content-Type: application/json" \
  -d '{
    "beneficiaryReference": "b3f1c2d4-5e6a-4b7c-8d9e-0f1a2b3c4d5e",
    "organizationReference": "b3f1c2d4-5e6a-4b7c-8d9e-0f1a2b3c4d5e",
    "productCode": "Ada Obi",
    "customerIdentifier": "March payroll",
    "saveBeneficiary": true,
    "beneficiaryAlias": "Ada Obi",
    "amount": {
      "amount": "250000.00",
      "currencyCode": "NGN"
    },
    "sourceAccountNumber": "0123456789",
    "instrumentReference": "b3f1c2d4-5e6a-4b7c-8d9e-0f1a2b3c4d5e",
    "validationReference": "b3f1c2d4-5e6a-4b7c-8d9e-0f1a2b3c4d5e",
    "fxQuoteReference": "b3f1c2d4-5e6a-4b7c-8d9e-0f1a2b3c4d5e",
    "narration": "March payroll"
  }'

{
  "beneficiaryReference": "b3f1c2d4-5e6a-4b7c-8d9e-0f1a2b3c4d5e",
  "organizationReference": "b3f1c2d4-5e6a-4b7c-8d9e-0f1a2b3c4d5e",
  "productCode": "Ada Obi",
  "customerIdentifier": "March payroll",
  "saveBeneficiary": true,
  "beneficiaryAlias": "Ada Obi",
  "amount": {
    "amount": "250000.00",
    "currencyCode": "NGN"
  },
  "sourceAccountNumber": "0123456789",
  "instrumentReference": "b3f1c2d4-5e6a-4b7c-8d9e-0f1a2b3c4d5e",
  "validationReference": "b3f1c2d4-5e6a-4b7c-8d9e-0f1a2b3c4d5e",
  "fxQuoteReference": "b3f1c2d4-5e6a-4b7c-8d9e-0f1a2b3c4d5e",
  "narration": "March payroll"
}

{
  "data": {
    "billPaymentReference": "b3f1c2d4-5e6a-4b7c-8d9e-0f1a2b3c4d5e",
    "beneficiaryReference": "b3f1c2d4-5e6a-4b7c-8d9e-0f1a2b3c4d5e",
    "saveBeneficiaryToken": "text",
    "status": "PENDING",
    "productCode": "Ada Obi",
    "customerIdentifier": "March payroll",
    "customerName": "Ada Obi",
    "amount": {
      "amount": "250000.00",
      "currencyCode": "NGN"
    },
    "amountDebited": {
      "amount": "250000.00",
      "currencyCode": "NGN"
    },
    "providerReference": "Ada Obi",
    "token": "March payroll",
    "tokenUnits": "March payroll",
    "accountsTransactionReference": "Ada Obi",
    "approvalReference": "b3f1c2d4-5e6a-4b7c-8d9e-0f1a2b3c4d5e",
    "failureReason": "March payroll",
    "timestamp": "2027-03-14T14:30:01"
  },
  "description": "Pay a bill"
}

Responses

Status	When
`200`	Bill payment processed
`400`	Amount is not allowed for this product; That beneficiary cannot be paid from here; The beneficiary and the bill details disagree; This bill must be paid from a wallet in its own currency; This quote does not match the transaction
`404`	Bill category not found; Bill product not found; Bill provider not found; Exchange rate quote not found; Validation not found or expired
`409`	Bill product is not available; Bill provider is not available; This exchange rate quote has already been used
`410`	This exchange rate quote has expired

GET Fetch a bill payment

GET /bill/payment/{reference}

Fetches one bill payment, including its current status and any token the biller returned.

Headers

Name	Notes
`Authorization`	Bearer token
`X-Tenant`	Your tenant
`X-Environment`	test or live

Path parameters

Name
`reference`

Example

Response: BillPaymentResponse

curl -X GET "https://api.bridgemoni.com/bill/payment/b3f1c2d4-5e6a-4b7c-8d9e-0f1a2b3c4d5e" \
  -H "Authorization: Bearer $BRIDGEMONI_TOKEN" \
  -H "X-Tenant: $BRIDGEMONI_TENANT" \
  -H "X-Environment: $BRIDGEMONI_ENV"

{
  "data": {
    "billPaymentReference": "b3f1c2d4-5e6a-4b7c-8d9e-0f1a2b3c4d5e",
    "beneficiaryReference": "b3f1c2d4-5e6a-4b7c-8d9e-0f1a2b3c4d5e",
    "saveBeneficiaryToken": "text",
    "status": "PENDING",
    "productCode": "Ada Obi",
    "customerIdentifier": "March payroll",
    "customerName": "Ada Obi",
    "amount": {
      "amount": "250000.00",
      "currencyCode": "NGN"
    },
    "amountDebited": {
      "amount": "250000.00",
      "currencyCode": "NGN"
    },
    "providerReference": "Ada Obi",
    "token": "March payroll",
    "tokenUnits": "March payroll",
    "accountsTransactionReference": "Ada Obi",
    "approvalReference": "b3f1c2d4-5e6a-4b7c-8d9e-0f1a2b3c4d5e",
    "failureReason": "March payroll",
    "timestamp": "2027-03-14T14:30:01"
  },
  "description": "Fetch a bill payment"
}

Responses

Status	When
`200`	Bill payment fetched successfully
`404`	Bill payment not found

POST Resolve a bill payment by hand

POST /bill/payment/{reference}/resolve

Records an operator's decision on a payment that could not be settled automatically. Guessing in either direction - refunding a bill that was paid, or claiming one that was not - is worse than asking, which is why this call exists.

Headers

Name	Notes
`Authorization`	Bearer token
`X-Tenant`	Your tenant
`X-Environment`	test or live
`Content-Type`	application/json

Path parameters

Name
`reference`

Example

Request body: ResolveBillPaymentRequest · Response: BillPaymentResponse

curl -X POST "https://api.bridgemoni.com/bill/payment/b3f1c2d4-5e6a-4b7c-8d9e-0f1a2b3c4d5e/resolve" \
  -H "Authorization: Bearer $BRIDGEMONI_TOKEN" \
  -H "X-Tenant: $BRIDGEMONI_TENANT" \
  -H "X-Environment: $BRIDGEMONI_ENV" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "PENDING",
    "reason": "March payroll"
  }'

{
  "status": "PENDING",
  "reason": "March payroll"
}

{
  "data": {
    "billPaymentReference": "b3f1c2d4-5e6a-4b7c-8d9e-0f1a2b3c4d5e",
    "beneficiaryReference": "b3f1c2d4-5e6a-4b7c-8d9e-0f1a2b3c4d5e",
    "saveBeneficiaryToken": "text",
    "status": "PENDING",
    "productCode": "Ada Obi",
    "customerIdentifier": "March payroll",
    "customerName": "Ada Obi",
    "amount": {
      "amount": "250000.00",
      "currencyCode": "NGN"
    },
    "amountDebited": {
      "amount": "250000.00",
      "currencyCode": "NGN"
    },
    "providerReference": "Ada Obi",
    "token": "March payroll",
    "tokenUnits": "March payroll",
    "accountsTransactionReference": "Ada Obi",
    "approvalReference": "b3f1c2d4-5e6a-4b7c-8d9e-0f1a2b3c4d5e",
    "failureReason": "March payroll",
    "timestamp": "2027-03-14T14:30:01"
  },
  "description": "Resolve a bill payment by hand"
}

Responses

Status	When
`200`	Bill payment resolved
`404`	Bill payment not found
`409`	Bill payment has already been finalized

GET List bill payments awaiting manual review

GET /bill/payments/review

Lists payments that could not be settled automatically because the provider never gave a usable answer and the requery attempts ran out. The money is still held against the provider.

Headers

Name	Notes
`Authorization`	Bearer token
`X-Tenant`	Your tenant
`X-Environment`	test or live

Example

Response: List<BillPaymentResponse>

curl -X GET "https://api.bridgemoni.com/bill/payments/review" \
  -H "Authorization: Bearer $BRIDGEMONI_TOKEN" \
  -H "X-Tenant: $BRIDGEMONI_TENANT" \
  -H "X-Environment: $BRIDGEMONI_ENV"

{
  "data": [
    {
      "billPaymentReference": "b3f1c2d4-5e6a-4b7c-8d9e-0f1a2b3c4d5e",
      "beneficiaryReference": "b3f1c2d4-5e6a-4b7c-8d9e-0f1a2b3c4d5e",
      "saveBeneficiaryToken": "text",
      "status": "PENDING",
      "productCode": "Ada Obi",
      "customerIdentifier": "March payroll",
      "customerName": "Ada Obi",
      "amount": {
        "amount": "250000.00",
        "currencyCode": "NGN"
      },
      "amountDebited": {
        "amount": "250000.00",
        "currencyCode": "NGN"
      },
      "providerReference": "Ada Obi",
      "token": "March payroll",
      "tokenUnits": "March payroll",
      "accountsTransactionReference": "Ada Obi",
      "approvalReference": "b3f1c2d4-5e6a-4b7c-8d9e-0f1a2b3c4d5e",
      "failureReason": "March payroll",
      "timestamp": "2027-03-14T14:30:01"
    }
  ],
  "description": "List bill payments awaiting manual review"
}

Responses

Status	When
`200`	Bill payments awaiting review fetched successfully

GET Look a product up by its biller and code

GET /bill/product

Finds one product by the codes that identify it, whatever its status - no reference needed, so an aggregator holding only its own codes can find it. Listing a biller's products returns only active ones, so this is the way to recover a withdrawn product: re-registering something withdrawn earlier is refused as a duplicate, and this is how it finds the reference to put back on sale instead. The aggregator is required alongside the biller code because the two together are what identify a biller; the code alone is not unique.

Headers

Name	Notes
`Authorization`	Bearer token
`X-Tenant`	Your tenant
`X-Environment`	test or live

Query parameters

Name	Default
`aggregatorCode`	Optional
`providerCode`	Optional
`productCode`	Optional

Example

Response: GenericResponseBillProductResponse

curl -X GET "https://api.bridgemoni.com/bill/product?aggregatorCode=value&providerCode=value&productCode=value" \
  -H "Authorization: Bearer $BRIDGEMONI_TOKEN" \
  -H "X-Tenant: $BRIDGEMONI_TENANT" \
  -H "X-Environment: $BRIDGEMONI_ENV"

{
  "data": {
    "reference": "b3f1c2d4-5e6a-4b7c-8d9e-0f1a2b3c4d5e",
    "productCode": {
      "name": "string"
    },
    "providerReference": "b3f1c2d4-5e6a-4b7c-8d9e-0f1a2b3c4d5e",
    "providerCode": {
      "providerCode": "string"
    },
    "aggregatorCode": "artx",
    "name": {
      "name": "string"
    },
    "pricingModel": "FIXED",
    "fixedAmount": 0,
    "minAmount": 0,
    "maxAmount": 0,
    "amountMultiple": 0,
    "currencyCode": "string",
    "validationRequired": true,
    "customerIdentifierLabel": "string",
    "customerIdentifierPattern": "string",
    "deliversToken": true,
    "status": "ACTIVE",
    "manuallyManaged": true,
    "extraParameters": [
      {
        "code": "accountType",
        "name": "Account type",
        "tip": "Prepaid or postpaid",
        "allowedValues": [
          "string"
        ],
        "mandatory": true
      }
    ],
    "feeCharges": [
      {
        "name": "VAT",
        "category": "TAX",
        "source": "PRODUCT",
        "pricingRuleReference": "b3f1c2d4-5e6a-4b7c-8d9e-0f1a2b3c4d5e",
        "rate": 0.075,
        "fixedAmount": 0,
        "basis": "AMOUNT",
        "amount": 7.5
      }
    ],
    "taxCharges": [
      {
        "name": "VAT",
        "category": "TAX",
        "source": "PRODUCT",
        "pricingRuleReference": "b3f1c2d4-5e6a-4b7c-8d9e-0f1a2b3c4d5e",
        "rate": 0.075,
        "fixedAmount": 0,
        "basis": "AMOUNT",
        "amount": 7.5
      }
    ],
    "commission": {
      "rate": 0.021,
      "fixedAmount": 0,
      "amount": 0
    }
  },
  "description": "Bill product fetched successfully"
}

Responses

Status	When
`200`	Bill product fetched successfully
`404`	Bill provider not found; Bill product not found

GET Fetch a product

GET /bill/product/{reference}

Fetches one product by reference, with the fees and taxes a customer pays on top of the amount. Tenant and operator callers also see the commission the product earns.

Headers

Name	Notes
`Authorization`	Bearer token
`X-Tenant`	Your tenant
`X-Environment`	test or live

Path parameters

Name
`reference`

Query parameters

Name	Default
`amount`	Optional

Example

Response: GenericResponseBillProductResponse

curl -X GET "https://api.bridgemoni.com/bill/product/b3f1c2d4-5e6a-4b7c-8d9e-0f1a2b3c4d5e" \
  -H "Authorization: Bearer $BRIDGEMONI_TOKEN" \
  -H "X-Tenant: $BRIDGEMONI_TENANT" \
  -H "X-Environment: $BRIDGEMONI_ENV"

{
  "data": {
    "reference": "b3f1c2d4-5e6a-4b7c-8d9e-0f1a2b3c4d5e",
    "productCode": {
      "name": "string"
    },
    "providerReference": "b3f1c2d4-5e6a-4b7c-8d9e-0f1a2b3c4d5e",
    "providerCode": {
      "providerCode": "string"
    },
    "aggregatorCode": "artx",
    "name": {
      "name": "string"
    },
    "pricingModel": "FIXED",
    "fixedAmount": 0,
    "minAmount": 0,
    "maxAmount": 0,
    "amountMultiple": 0,
    "currencyCode": "string",
    "validationRequired": true,
    "customerIdentifierLabel": "string",
    "customerIdentifierPattern": "string",
    "deliversToken": true,
    "status": "ACTIVE",
    "manuallyManaged": true,
    "extraParameters": [
      {
        "code": "accountType",
        "name": "Account type",
        "tip": "Prepaid or postpaid",
        "allowedValues": [
          "string"
        ],
        "mandatory": true
      }
    ],
    "feeCharges": [
      {
        "name": "VAT",
        "category": "TAX",
        "source": "PRODUCT",
        "pricingRuleReference": "b3f1c2d4-5e6a-4b7c-8d9e-0f1a2b3c4d5e",
        "rate": 0.075,
        "fixedAmount": 0,
        "basis": "AMOUNT",
        "amount": 7.5
      }
    ],
    "taxCharges": [
      {
        "name": "VAT",
        "category": "TAX",
        "source": "PRODUCT",
        "pricingRuleReference": "b3f1c2d4-5e6a-4b7c-8d9e-0f1a2b3c4d5e",
        "rate": 0.075,
        "fixedAmount": 0,
        "basis": "AMOUNT",
        "amount": 7.5
      }
    ],
    "commission": {
      "rate": 0.021,
      "fixedAmount": 0,
      "amount": 0
    }
  },
  "description": "Bill product fetched successfully"
}

Responses

Status	When
`200`	Bill product fetched successfully
`404`	Bill product not found

PUT Override a synced product's presentation

PUT /bill/product/{reference}/override

Curates a product that catalogue sync owns. The sync never writes these fields, so an override survives every refresh.

Headers

Name	Notes
`Authorization`	Bearer token
`X-Tenant`	Your tenant
`X-Environment`	test or live
`Content-Type`	application/json

Path parameters

Name
`reference`

Example

Request body: BillProductOverrideRequest · Response: BillProductResponse

curl -X PUT "https://api.bridgemoni.com/bill/product/b3f1c2d4-5e6a-4b7c-8d9e-0f1a2b3c4d5e/override" \
  -H "Authorization: Bearer $BRIDGEMONI_TOKEN" \
  -H "X-Tenant: $BRIDGEMONI_TENANT" \
  -H "X-Environment: $BRIDGEMONI_ENV" \
  -H "Content-Type: application/json" \
  -d '{
    "displayName": "Ada Obi",
    "enabled": true,
    "marginRateOverride": 250000.0,
    "minAmountOverride": 250000.0,
    "maxAmountOverride": 250000.0,
    "note": "March payroll"
  }'

{
  "displayName": "Ada Obi",
  "enabled": true,
  "marginRateOverride": 250000.0,
  "minAmountOverride": 250000.0,
  "maxAmountOverride": 250000.0,
  "note": "March payroll"
}

{
  "data": {
    "reference": "b3f1c2d4-5e6a-4b7c-8d9e-0f1a2b3c4d5e",
    "productCode": "Ada Obi",
    "providerReference": "b3f1c2d4-5e6a-4b7c-8d9e-0f1a2b3c4d5e",
    "providerCode": "provider code",
    "name": "Ada Obi",
    "pricingModel": "FIXED",
    "fixedAmount": 250000.0,
    "minAmount": 250000.0,
    "maxAmount": 250000.0,
    "amountMultiple": 250000.0,
    "currencyCode": "NGN",
    "validationRequired": true,
    "customerIdentifierLabel": "March payroll",
    "customerIdentifierPattern": "March payroll",
    "deliversToken": true,
    "status": "ACTIVE"
  },
  "description": "Override a synced product's presentation"
}

Responses

Status	When
`200`	Bill product override applied successfully
`404`	Bill product not found; Bill provider not found

GET Look a biller up by its aggregator and code

GET /bill/provider

Finds one biller by the pair that identifies it in an aggregator's feed, whatever its status. Listing a category returns only active billers, so this is the way to recover a deactivated one - an aggregator re-registering a biller it withdrew earlier is refused as a duplicate, and this is how it finds the reference to reactivate instead.

Headers

Name	Notes
`Authorization`	Bearer token
`X-Tenant`	Your tenant
`X-Environment`	test or live

Query parameters

Name	Default
`aggregatorCode`	Optional
`providerCode`	Optional

Example

Response: GenericResponseBillProviderResponse

curl -X GET "https://api.bridgemoni.com/bill/provider?aggregatorCode=value&providerCode=value" \
  -H "Authorization: Bearer $BRIDGEMONI_TOKEN" \
  -H "X-Tenant: $BRIDGEMONI_TENANT" \
  -H "X-Environment: $BRIDGEMONI_ENV"

{
  "data": {
    "reference": "b3f1c2d4-5e6a-4b7c-8d9e-0f1a2b3c4d5e",
    "providerCode": {
      "providerCode": "string"
    },
    "aggregatorCode": {
      "name": "string"
    },
    "name": {
      "name": "string"
    },
    "brandId": "mtn-ng",
    "categoryReference": "b3f1c2d4-5e6a-4b7c-8d9e-0f1a2b3c4d5e",
    "countryCode": "string",
    "currencyCode": "string",
    "status": "ACTIVE",
    "supportsValidation": true,
    "supportsRequery": true,
    "priority": "1",
    "manuallyManaged": true
  },
  "description": "Bill provider fetched successfully"
}

Responses

Status	When
`200`	Bill provider fetched successfully
`404`	Bill provider not found

GET Fetch a biller

GET /bill/provider/{reference}

Fetches one biller by reference.

Headers

Name	Notes
`Authorization`	Bearer token
`X-Tenant`	Your tenant
`X-Environment`	test or live

Path parameters

Name
`reference`

Example

Response: GenericResponseBillProviderResponse

curl -X GET "https://api.bridgemoni.com/bill/provider/b3f1c2d4-5e6a-4b7c-8d9e-0f1a2b3c4d5e" \
  -H "Authorization: Bearer $BRIDGEMONI_TOKEN" \
  -H "X-Tenant: $BRIDGEMONI_TENANT" \
  -H "X-Environment: $BRIDGEMONI_ENV"

{
  "data": {
    "reference": "b3f1c2d4-5e6a-4b7c-8d9e-0f1a2b3c4d5e",
    "providerCode": {
      "providerCode": "string"
    },
    "aggregatorCode": {
      "name": "string"
    },
    "name": {
      "name": "string"
    },
    "brandId": "mtn-ng",
    "categoryReference": "b3f1c2d4-5e6a-4b7c-8d9e-0f1a2b3c4d5e",
    "countryCode": "string",
    "currencyCode": "string",
    "status": "ACTIVE",
    "supportsValidation": true,
    "supportsRequery": true,
    "priority": "1",
    "manuallyManaged": true
  },
  "description": "Bill provider fetched successfully"
}

Responses

Status	When
`200`	Bill provider fetched successfully
`404`	Bill provider not found

GET List a biller's products

GET /bill/provider/{reference}/products

Lists the products a biller offers. A product declares whether validation is required before payment is accepted, and carries the fees and taxes a customer pays on top of the amount - the product's own, then the tenant's pricing rules for bill payments. Tenant and operator callers also see the commission each product earns.

Headers

Name	Notes
`Authorization`	Bearer token
`X-Tenant`	Your tenant
`X-Environment`	test or live

Path parameters

Name
`reference`

Example

Response: List<BillProductResponse>

curl -X GET "https://api.bridgemoni.com/bill/provider/b3f1c2d4-5e6a-4b7c-8d9e-0f1a2b3c4d5e/products" \
  -H "Authorization: Bearer $BRIDGEMONI_TOKEN" \
  -H "X-Tenant: $BRIDGEMONI_TENANT" \
  -H "X-Environment: $BRIDGEMONI_ENV"

{
  "data": [
    {
      "reference": "b3f1c2d4-5e6a-4b7c-8d9e-0f1a2b3c4d5e",
      "productCode": "Ada Obi",
      "providerReference": "b3f1c2d4-5e6a-4b7c-8d9e-0f1a2b3c4d5e",
      "providerCode": "provider code",
      "name": "Ada Obi",
      "pricingModel": "FIXED",
      "fixedAmount": 250000.0,
      "minAmount": 250000.0,
      "maxAmount": 250000.0,
      "amountMultiple": 250000.0,
      "currencyCode": "NGN",
      "validationRequired": true,
      "customerIdentifierLabel": "March payroll",
      "customerIdentifierPattern": "March payroll",
      "deliversToken": true,
      "status": "ACTIVE"
    }
  ],
  "description": "List a biller's products"
}

Responses

Status	When
`200`	Bill products fetched successfully
`404`	Bill provider not found

POST Schedule a bill

POST /bill/schedule

Sets a saved bill to be paid on a cadence. Nothing is paid by this call. Requires a validated transaction PIN: a schedule is standing authority to debit a wallet, which is the same authority as paying by hand. The amount is a mode, not a number. FIXED is checked against the product's own rules here - its range, and the multiple it requires - so an amount the biller would reject is refused now rather than at one in the morning on the first of the month. AMOUNT_DUE and CAPPED_AMOUNT_DUE need a product the biller will quote a balance for.

Headers

Name	Notes
`Authorization`	Bearer token
`X-Tenant`	Your tenant
`X-Environment`	test or live
`Content-Type`	application/json

Example

Request body: BillScheduleRequest · Response: GenericResponseBillScheduleResponse

curl -X POST "https://api.bridgemoni.com/bill/schedule" \
  -H "Authorization: Bearer $BRIDGEMONI_TOKEN" \
  -H "X-Tenant: $BRIDGEMONI_TENANT" \
  -H "X-Environment: $BRIDGEMONI_ENV" \
  -H "Content-Type: application/json" \
  -d '{
  "billReference": "b3f1c2d4-5e6a-4b7c-8d9e-0f1a2b3c4d5e",
  "name": "Monthly electricity",
  "sourceAccountNumber": 1000000199,
  "amountMode": "FIXED",
  "fixedAmount": 5000.0,
  "maximumAmount": 25000.0,
  "frequency": "DAILY",
  "dayOfMonth": 5,
  "dayOfWeek": 3,
  "startsOn": "2026-10-01",
  "endsOn": "2027-10-01",
  "maximumOccurrences": 12
}'

{
  "billReference": "b3f1c2d4-5e6a-4b7c-8d9e-0f1a2b3c4d5e",
  "name": "Monthly electricity",
  "sourceAccountNumber": 1000000199,
  "amountMode": "FIXED",
  "fixedAmount": 5000.0,
  "maximumAmount": 25000.0,
  "frequency": "DAILY",
  "dayOfMonth": 5,
  "dayOfWeek": 3,
  "startsOn": "2026-10-01",
  "endsOn": "2027-10-01",
  "maximumOccurrences": 12
}

{
  "data": {
    "reference": "b3f1c2d4-5e6a-4b7c-8d9e-0f1a2b3c4d5e",
    "billReference": "b3f1c2d4-5e6a-4b7c-8d9e-0f1a2b3c4d5e",
    "billName": {
      "name": "string"
    },
    "name": {
      "name": "string"
    },
    "sourceAccountNumber": "string",
    "amountMode": "FIXED",
    "fixedAmount": {
      "amount": "10000.00",
      "currencyCode": "NGN"
    },
    "maximumAmount": {
      "amount": "10000.00",
      "currencyCode": "NGN"
    },
    "currencyCode": "string",
    "frequency": "DAILY",
    "dayOfMonth": 0,
    "dayOfWeek": 0,
    "nextRunAt": "2026-09-25T10:00:00Z",
    "startAt": "2026-09-25T10:00:00Z",
    "endAt": "2026-09-25T10:00:00Z",
    "maximumOccurrences": 0,
    "occurrenceCount": 0,
    "status": "ACTIVE",
    "consecutiveFailureCount": 0,
    "lastFailureCode": "string",
    "lastRunAt": "2026-09-25T10:00:00Z",
    "lastRunOutcome": "string",
    "creationDateTime": "2026-09-25T10:00:00Z"
  },
  "description": "Schedule created successfully"
}

Responses

Status	When
`200`	Schedule created successfully
`400`	The cadence is incomplete - a monthly schedule needs a day of the month from 1 to 28, a weekly one a day of the week - or the amount is one the product does not allow
`403`	No validated transaction PIN
`404`	No such saved bill
`409`	The mode needs a product that quotes a balance and this one does not

GET Read one bill schedule

GET /bill/schedule/{reference}

Headers

Name	Notes
`Authorization`	Bearer token
`X-Tenant`	Your tenant
`X-Environment`	test or live

Path parameters

Name
`reference`

Example

Response: GenericResponseBillScheduleResponse

curl -X GET "https://api.bridgemoni.com/bill/schedule/b3f1c2d4-5e6a-4b7c-8d9e-0f1a2b3c4d5e" \
  -H "Authorization: Bearer $BRIDGEMONI_TOKEN" \
  -H "X-Tenant: $BRIDGEMONI_TENANT" \
  -H "X-Environment: $BRIDGEMONI_ENV"

{
  "data": {
    "reference": "b3f1c2d4-5e6a-4b7c-8d9e-0f1a2b3c4d5e",
    "billReference": "b3f1c2d4-5e6a-4b7c-8d9e-0f1a2b3c4d5e",
    "billName": {
      "name": "string"
    },
    "name": {
      "name": "string"
    },
    "sourceAccountNumber": "string",
    "amountMode": "FIXED",
    "fixedAmount": {
      "amount": "10000.00",
      "currencyCode": "NGN"
    },
    "maximumAmount": {
      "amount": "10000.00",
      "currencyCode": "NGN"
    },
    "currencyCode": "string",
    "frequency": "DAILY",
    "dayOfMonth": 0,
    "dayOfWeek": 0,
    "nextRunAt": "2026-09-25T10:00:00Z",
    "startAt": "2026-09-25T10:00:00Z",
    "endAt": "2026-09-25T10:00:00Z",
    "maximumOccurrences": 0,
    "occurrenceCount": 0,
    "status": "ACTIVE",
    "consecutiveFailureCount": 0,
    "lastFailureCode": "string",
    "lastRunAt": "2026-09-25T10:00:00Z",
    "lastRunOutcome": "string",
    "creationDateTime": "2026-09-25T10:00:00Z"
  },
  "description": "Schedule retrieved successfully"
}

Responses

Status	When
`200`	Schedule retrieved successfully
`404`	No such schedule, or it belongs to somebody else - both read the same way deliberately

POST Cancel a bill schedule

POST /bill/schedule/{reference}/cancel

Terminal. The payments it already made are kept.

Headers

Name	Notes
`Authorization`	Bearer token
`X-Tenant`	Your tenant
`X-Environment`	test or live

Path parameters

Name
`reference`

Example

Response: GenericResponseBillScheduleResponse

curl -X POST "https://api.bridgemoni.com/bill/schedule/b3f1c2d4-5e6a-4b7c-8d9e-0f1a2b3c4d5e/cancel" \
  -H "Authorization: Bearer $BRIDGEMONI_TOKEN" \
  -H "X-Tenant: $BRIDGEMONI_TENANT" \
  -H "X-Environment: $BRIDGEMONI_ENV"

{
  "data": {
    "reference": "b3f1c2d4-5e6a-4b7c-8d9e-0f1a2b3c4d5e",
    "billReference": "b3f1c2d4-5e6a-4b7c-8d9e-0f1a2b3c4d5e",
    "billName": {
      "name": "string"
    },
    "name": {
      "name": "string"
    },
    "sourceAccountNumber": "string",
    "amountMode": "FIXED",
    "fixedAmount": {
      "amount": "10000.00",
      "currencyCode": "NGN"
    },
    "maximumAmount": {
      "amount": "10000.00",
      "currencyCode": "NGN"
    },
    "currencyCode": "string",
    "frequency": "DAILY",
    "dayOfMonth": 0,
    "dayOfWeek": 0,
    "nextRunAt": "2026-09-25T10:00:00Z",
    "startAt": "2026-09-25T10:00:00Z",
    "endAt": "2026-09-25T10:00:00Z",
    "maximumOccurrences": 0,
    "occurrenceCount": 0,
    "status": "ACTIVE",
    "consecutiveFailureCount": 0,
    "lastFailureCode": "string",
    "lastRunAt": "2026-09-25T10:00:00Z",
    "lastRunOutcome": "string",
    "creationDateTime": "2026-09-25T10:00:00Z"
  },
  "description": "Schedule cancelled successfully"
}

Responses

Status	When
`200`	Schedule cancelled successfully
`409`	It has already ended

POST Pause a bill schedule

POST /bill/schedule/{reference}/pause

Stops it firing. The dates it misses while paused are not paid later.

Headers

Name	Notes
`Authorization`	Bearer token
`X-Tenant`	Your tenant
`X-Environment`	test or live

Path parameters

Name
`reference`

Example

Response: GenericResponseBillScheduleResponse

curl -X POST "https://api.bridgemoni.com/bill/schedule/b3f1c2d4-5e6a-4b7c-8d9e-0f1a2b3c4d5e/pause" \
  -H "Authorization: Bearer $BRIDGEMONI_TOKEN" \
  -H "X-Tenant: $BRIDGEMONI_TENANT" \
  -H "X-Environment: $BRIDGEMONI_ENV"

{
  "data": {
    "reference": "b3f1c2d4-5e6a-4b7c-8d9e-0f1a2b3c4d5e",
    "billReference": "b3f1c2d4-5e6a-4b7c-8d9e-0f1a2b3c4d5e",
    "billName": {
      "name": "string"
    },
    "name": {
      "name": "string"
    },
    "sourceAccountNumber": "string",
    "amountMode": "FIXED",
    "fixedAmount": {
      "amount": "10000.00",
      "currencyCode": "NGN"
    },
    "maximumAmount": {
      "amount": "10000.00",
      "currencyCode": "NGN"
    },
    "currencyCode": "string",
    "frequency": "DAILY",
    "dayOfMonth": 0,
    "dayOfWeek": 0,
    "nextRunAt": "2026-09-25T10:00:00Z",
    "startAt": "2026-09-25T10:00:00Z",
    "endAt": "2026-09-25T10:00:00Z",
    "maximumOccurrences": 0,
    "occurrenceCount": 0,
    "status": "ACTIVE",
    "consecutiveFailureCount": 0,
    "lastFailureCode": "string",
    "lastRunAt": "2026-09-25T10:00:00Z",
    "lastRunOutcome": "string",
    "creationDateTime": "2026-09-25T10:00:00Z"
  },
  "description": "Schedule paused successfully"
}

Responses

Status	When
`200`	Schedule paused successfully
`409`	It is not active, or has already ended

POST Resume a bill schedule

POST /bill/schedule/{reference}/resume

Starts it firing again from the next date, not from the ones it missed. Catching up on a pause would debit a wallet several times over for periods the payer chose not to pay.

Headers

Name	Notes
`Authorization`	Bearer token
`X-Tenant`	Your tenant
`X-Environment`	test or live

Path parameters

Name
`reference`

Example

Response: GenericResponseBillScheduleResponse

curl -X POST "https://api.bridgemoni.com/bill/schedule/b3f1c2d4-5e6a-4b7c-8d9e-0f1a2b3c4d5e/resume" \
  -H "Authorization: Bearer $BRIDGEMONI_TOKEN" \
  -H "X-Tenant: $BRIDGEMONI_TENANT" \
  -H "X-Environment: $BRIDGEMONI_ENV"

{
  "data": {
    "reference": "b3f1c2d4-5e6a-4b7c-8d9e-0f1a2b3c4d5e",
    "billReference": "b3f1c2d4-5e6a-4b7c-8d9e-0f1a2b3c4d5e",
    "billName": {
      "name": "string"
    },
    "name": {
      "name": "string"
    },
    "sourceAccountNumber": "string",
    "amountMode": "FIXED",
    "fixedAmount": {
      "amount": "10000.00",
      "currencyCode": "NGN"
    },
    "maximumAmount": {
      "amount": "10000.00",
      "currencyCode": "NGN"
    },
    "currencyCode": "string",
    "frequency": "DAILY",
    "dayOfMonth": 0,
    "dayOfWeek": 0,
    "nextRunAt": "2026-09-25T10:00:00Z",
    "startAt": "2026-09-25T10:00:00Z",
    "endAt": "2026-09-25T10:00:00Z",
    "maximumOccurrences": 0,
    "occurrenceCount": 0,
    "status": "ACTIVE",
    "consecutiveFailureCount": 0,
    "lastFailureCode": "string",
    "lastRunAt": "2026-09-25T10:00:00Z",
    "lastRunOutcome": "string",
    "creationDateTime": "2026-09-25T10:00:00Z"
  },
  "description": "Schedule resumed successfully"
}

Responses

Status	When
`200`	Schedule resumed successfully
`409`	It is not paused, or has already ended

POST Run a bill schedule now

POST /bill/schedule/{reference}/run

Pays this schedule's next occurrence immediately, through the same code an automatic run uses. A manual run and an automatic one produce the same run row, the same double-payment guard and the same failure accounting, and the occurrence is consumed either way - so the period is paid once, not once by hand and again by the clock. Requires a validated transaction PIN. A run that could not pay still answers 200: the run row is the answer, and it carries the status and the reason. Read failureCode to tell a short wallet from a withdrawn product.

Headers

Name	Notes
`Authorization`	Bearer token
`X-Tenant`	Your tenant
`X-Environment`	test or live

Path parameters

Name
`reference`

Example

Response: GenericResponseBillScheduleRunResponse

curl -X POST "https://api.bridgemoni.com/bill/schedule/b3f1c2d4-5e6a-4b7c-8d9e-0f1a2b3c4d5e/run" \
  -H "Authorization: Bearer $BRIDGEMONI_TOKEN" \
  -H "X-Tenant: $BRIDGEMONI_TENANT" \
  -H "X-Environment: $BRIDGEMONI_ENV"

{
  "data": {
    "reference": "b3f1c2d4-5e6a-4b7c-8d9e-0f1a2b3c4d5e",
    "scheduleReference": "b3f1c2d4-5e6a-4b7c-8d9e-0f1a2b3c4d5e",
    "billReference": "b3f1c2d4-5e6a-4b7c-8d9e-0f1a2b3c4d5e",
    "occurrenceNumber": 0,
    "scheduledFor": "2026-09-25T10:00:00Z",
    "trigger": "SCHEDULED",
    "validationReference": "b3f1c2d4-5e6a-4b7c-8d9e-0f1a2b3c4d5e",
    "outstandingAmount": {
      "amount": "10000.00",
      "currencyCode": "NGN"
    },
    "resolvedAmount": {
      "amount": "10000.00",
      "currencyCode": "NGN"
    },
    "currencyCode": "string",
    "paymentReference": "b3f1c2d4-5e6a-4b7c-8d9e-0f1a2b3c4d5e",
    "status": "PENDING",
    "failureCode": "string",
    "failureReason": "string",
    "completedAt": "2026-09-25T10:00:00Z",
    "creationDateTime": "2026-09-25T10:00:00Z"
  },
  "description": "The run was recorded. SUCCESSFUL, PENDING while the payment is in flight, SKIPPED when the biller reported nothing owed, or FAILED with a reason"
}

Responses

Status	When
`200`	The run was recorded. SUCCESSFUL, PENDING while the payment is in flight, SKIPPED when the biller reported nothing owed, or FAILED with a reason
`403`	No validated transaction PIN
`404`	No such schedule
`409`	It is paused, a pass is already working it, or it has already ended

GET List a schedule's runs

GET /bill/schedule/{reference}/runs

Most recent occurrence first. Every firing is here, including the ones that were skipped or failed, because a payer asking why a bill went unpaid needs the refusal as much as the payments.

Headers

Name	Notes
`Authorization`	Bearer token
`X-Tenant`	Your tenant
`X-Environment`	test or live

Path parameters

Name
`reference`

Query parameters

Name	Default
`page`	0
`size`	20

Example

Response: GenericResponsePagerBillScheduleRunResponse

curl -X GET "https://api.bridgemoni.com/bill/schedule/b3f1c2d4-5e6a-4b7c-8d9e-0f1a2b3c4d5e/runs?page=value&size=20" \
  -H "Authorization: Bearer $BRIDGEMONI_TOKEN" \
  -H "X-Tenant: $BRIDGEMONI_TENANT" \
  -H "X-Environment: $BRIDGEMONI_ENV"

{
  "data": {
    "content": [
      {
        "reference": "b3f1c2d4-5e6a-4b7c-8d9e-0f1a2b3c4d5e",
        "scheduleReference": "b3f1c2d4-5e6a-4b7c-8d9e-0f1a2b3c4d5e",
        "billReference": "b3f1c2d4-5e6a-4b7c-8d9e-0f1a2b3c4d5e",
        "occurrenceNumber": 0,
        "scheduledFor": "2026-09-25T10:00:00Z",
        "trigger": "SCHEDULED",
        "validationReference": "b3f1c2d4-5e6a-4b7c-8d9e-0f1a2b3c4d5e",
        "outstandingAmount": {
          "amount": "10000.00",
          "currencyCode": "NGN"
        },
        "resolvedAmount": {
          "amount": "10000.00",
          "currencyCode": "NGN"
        },
        "currencyCode": "string",
        "paymentReference": "b3f1c2d4-5e6a-4b7c-8d9e-0f1a2b3c4d5e",
        "status": "PENDING",
        "failureCode": "string",
        "failureReason": "string",
        "completedAt": "2026-09-25T10:00:00Z",
        "creationDateTime": "2026-09-25T10:00:00Z"
      }
    ],
    "page": "1",
    "size": "1",
    "totalPages": "1",
    "totalElements": "1"
  },
  "description": "Runs retrieved successfully"
}

Responses

Status	When
`200`	Runs retrieved successfully

GET List your bill schedules

GET /bill/schedules

Active schedules unless a status is named.

Headers

Name	Notes
`Authorization`	Bearer token
`X-Tenant`	Your tenant
`X-Environment`	test or live

Query parameters

Name	Default
`status`	Optional
`page`	0
`size`	20

Example

Response: GenericResponsePagerBillScheduleResponse

curl -X GET "https://api.bridgemoni.com/bill/schedules?page=value&size=20" \
  -H "Authorization: Bearer $BRIDGEMONI_TOKEN" \
  -H "X-Tenant: $BRIDGEMONI_TENANT" \
  -H "X-Environment: $BRIDGEMONI_ENV"

{
  "data": {
    "content": [
      {
        "reference": "b3f1c2d4-5e6a-4b7c-8d9e-0f1a2b3c4d5e",
        "billReference": "b3f1c2d4-5e6a-4b7c-8d9e-0f1a2b3c4d5e",
        "billName": {
          "name": "string"
        },
        "name": {
          "name": "string"
        },
        "sourceAccountNumber": "string",
        "amountMode": "FIXED",
        "fixedAmount": {
          "amount": "10000.00",
          "currencyCode": "NGN"
        },
        "maximumAmount": {
          "amount": "10000.00",
          "currencyCode": "NGN"
        },
        "currencyCode": "string",
        "frequency": "DAILY",
        "dayOfMonth": 0,
        "dayOfWeek": 0,
        "nextRunAt": "2026-09-25T10:00:00Z",
        "startAt": "2026-09-25T10:00:00Z",
        "endAt": "2026-09-25T10:00:00Z",
        "maximumOccurrences": 0,
        "occurrenceCount": 0,
        "status": "ACTIVE",
        "consecutiveFailureCount": 0,
        "lastFailureCode": "string",
        "lastRunAt": "2026-09-25T10:00:00Z",
        "lastRunOutcome": "string",
        "creationDateTime": "2026-09-25T10:00:00Z"
      }
    ],
    "page": "1",
    "size": "1",
    "totalPages": "1",
    "totalElements": "1"
  },
  "description": "Schedules retrieved successfully"
}

Responses

Status	When
`200`	Schedules retrieved successfully

POST Validate a customer identifier at the biller

POST /bill/validate

Resolves a customer identifier - a meter number, an account, a smartcard - at the biller before any money moves, and returns the name the biller holds against it. Quote the returned reference on the payment. For a product that declares validationRequired, payment is refused without one: paying the wrong meter cannot be undone.

Headers

Name	Notes
`Authorization`	Bearer token
`X-Tenant`	Your tenant
`X-Environment`	test or live
`Content-Type`	application/json

Example

Request body: BillValidationRequest · Response: BillValidationResponse

curl -X POST "https://api.bridgemoni.com/bill/validate" \
  -H "Authorization: Bearer $BRIDGEMONI_TOKEN" \
  -H "X-Tenant: $BRIDGEMONI_TENANT" \
  -H "X-Environment: $BRIDGEMONI_ENV" \
  -H "Content-Type: application/json" \
  -d '{
    "productCode": "Ada Obi",
    "customerIdentifier": "March payroll"
  }'

{
  "productCode": "Ada Obi",
  "customerIdentifier": "March payroll"
}

{
  "data": {
    "reference": "b3f1c2d4-5e6a-4b7c-8d9e-0f1a2b3c4d5e",
    "status": "RESOLVED",
    "productCode": "Ada Obi",
    "customerIdentifier": "March payroll",
    "customerName": "Ada Obi",
    "outstandingAmount": 250000.0,
    "currencyCode": "NGN",
    "providerMessage": "March payroll",
    "expiresAt": "2027-03-14T14:30:01"
  },
  "description": "Validate a customer identifier at the biller"
}

Responses

Status	When
`200`	Bill validation completed successfully
`404`	Bill category not found; Bill product not found; Bill provider not found
`409`	Bill product is not available; Bill provider is not available
`500`	Could not validate this customer identifier

GET Read one saved bill

GET /bill/{reference}

Headers

Name	Notes
`Authorization`	Bearer token
`X-Tenant`	Your tenant
`X-Environment`	test or live

Path parameters

Name
`reference`

Example

Response: GenericResponseBillResponse

curl -X GET "https://api.bridgemoni.com/bill/b3f1c2d4-5e6a-4b7c-8d9e-0f1a2b3c4d5e" \
  -H "Authorization: Bearer $BRIDGEMONI_TOKEN" \
  -H "X-Tenant: $BRIDGEMONI_TENANT" \
  -H "X-Environment: $BRIDGEMONI_ENV"

{
  "data": {
    "reference": "b3f1c2d4-5e6a-4b7c-8d9e-0f1a2b3c4d5e",
    "name": "Ikeja Electric - Flat 3",
    "description": "string",
    "accountNumber": "45012345678",
    "maskedAccountNumber": "*******5678",
    "accountName": "ADA OKAFOR",
    "accountNameConfirmedAt": "2026-09-25T10:00:00Z",
    "productCode": "IKEDC_PREPAID",
    "providerCode": "IKEDC",
    "providerName": "Ikeja Electric",
    "categoryCode": "ELECTRICITY",
    "categoryName": "Electricity",
    "currencyCode": "NGN",
    "status": "string",
    "creationDateTime": "2026-09-25T10:00:00Z",
    "amount": 5000.0,
    "schedule": {
      "reference": "b3f1c2d4-5e6a-4b7c-8d9e-0f1a2b3c4d5e",
      "billReference": "b3f1c2d4-5e6a-4b7c-8d9e-0f1a2b3c4d5e",
      "billName": {
        "name": "string"
      },
      "name": {
        "name": "string"
      },
      "sourceAccountNumber": "string",
      "amountMode": "FIXED",
      "fixedAmount": {
        "amount": "10000.00",
        "currencyCode": "NGN"
      },
      "maximumAmount": {
        "amount": "10000.00",
        "currencyCode": "NGN"
      },
      "currencyCode": "string",
      "frequency": "DAILY",
      "dayOfMonth": 0,
      "dayOfWeek": 0,
      "nextRunAt": "2026-09-25T10:00:00Z",
      "startAt": "2026-09-25T10:00:00Z",
      "endAt": "2026-09-25T10:00:00Z",
      "maximumOccurrences": 0,
      "occurrenceCount": 0,
      "status": "ACTIVE",
      "consecutiveFailureCount": 0,
      "lastFailureCode": "string",
      "lastRunAt": "2026-09-25T10:00:00Z",
      "lastRunOutcome": "string",
      "creationDateTime": "2026-09-25T10:00:00Z"
    }
  },
  "description": "Bill retrieved successfully"
}

Responses

Status	When
`200`	Bill retrieved successfully
`404`	No saved bill for that reference. A saved payee of another kind reads the same way, because a bill is the only kind this endpoint speaks for

GET List your saved bills

GET /bills

Active bills only. Archived ones are kept but not listed.

Headers

Name	Notes
`Authorization`	Bearer token
`X-Tenant`	Your tenant
`X-Environment`	test or live

Query parameters

Name	Default
`page`	0
`size`	20

Example

Response: GenericResponsePagerBillResponse

curl -X GET "https://api.bridgemoni.com/bills?page=value&size=20" \
  -H "Authorization: Bearer $BRIDGEMONI_TOKEN" \
  -H "X-Tenant: $BRIDGEMONI_TENANT" \
  -H "X-Environment: $BRIDGEMONI_ENV"

{
  "data": {
    "content": [
      {
        "reference": "b3f1c2d4-5e6a-4b7c-8d9e-0f1a2b3c4d5e",
        "name": "Ikeja Electric - Flat 3",
        "description": "string",
        "accountNumber": "45012345678",
        "maskedAccountNumber": "*******5678",
        "accountName": "ADA OKAFOR",
        "accountNameConfirmedAt": "2026-09-25T10:00:00Z",
        "productCode": "IKEDC_PREPAID",
        "providerCode": "IKEDC",
        "providerName": "Ikeja Electric",
        "categoryCode": "ELECTRICITY",
        "categoryName": "Electricity",
        "currencyCode": "NGN",
        "status": "string",
        "creationDateTime": "2026-09-25T10:00:00Z",
        "amount": 5000.0,
        "schedule": {
          "reference": "b3f1c2d4-5e6a-4b7c-8d9e-0f1a2b3c4d5e",
          "billReference": "b3f1c2d4-5e6a-4b7c-8d9e-0f1a2b3c4d5e",
          "billName": {
            "name": "string"
          },
          "name": {
            "name": "string"
          },
          "sourceAccountNumber": "string",
          "amountMode": "FIXED",
          "fixedAmount": {
            "amount": "10000.00",
            "currencyCode": "NGN"
          },
          "maximumAmount": {
            "amount": "10000.00",
            "currencyCode": "NGN"
          },
          "currencyCode": "string",
          "frequency": "DAILY",
          "dayOfMonth": 0,
          "dayOfWeek": 0,
          "nextRunAt": "2026-09-25T10:00:00Z",
          "startAt": "2026-09-25T10:00:00Z",
          "endAt": "2026-09-25T10:00:00Z",
          "maximumOccurrences": 0,
          "occurrenceCount": 0,
          "status": "ACTIVE",
          "consecutiveFailureCount": 0,
          "lastFailureCode": "string",
          "lastRunAt": "2026-09-25T10:00:00Z",
          "lastRunOutcome": "string",
          "creationDateTime": "2026-09-25T10:00:00Z"
        }
      }
    ],
    "page": "1",
    "size": "1",
    "totalPages": "1",
    "totalElements": "1"
  },
  "description": "Bills retrieved successfully"
}

Responses

Status	When
`200`	Bills retrieved successfully

Generated from the OpenAPI document. Branch on the HTTP status: there is no machine-readable error code on the wire. Errors