Bill payments

Bill payment

Request

POST https://api-dev.spay.ng/api/v1/bill-debits
Authorization: Bearer <access-token>
Accept: application/json
Content-Type: application/json

{
  "sourceAccountNumber": "8880000001",
  "amount": 2500.0,
  "narration": "Electricity purchase",
  "reference": "bill-pos-0001"
}

curl -X POST 'https://api-dev.spay.ng/api/v1/bill-debits' \
  -H "Authorization: Bearer $SPAY_ACCESS_TOKEN" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
  "sourceAccountNumber": "8880000001",
  "amount": 2500.0,
  "narration": "Electricity purchase",
  "reference": "bill-pos-0001"
}'

Response: 202 Accepted

{
  "reference": "bill-pos-0001",
  "originalReference": null,
  "ownerAccountNumber": "8880000001",
  "type": "BILL_PAYMENT_DEBIT",
  "mode": "DEBIT",
  "status": "PENDING",
  "reviewRequired": false,
  "amount": 2500.0,
  "feeAmount": 0.0,
  "currency": "NGN",
  "source": {
    "accountNumber": "8880000001",
    "accountName": "Adunni Foods"
  },
  "beneficiary": {
    "accountNumber": "8880000099",
    "accountName": "POS Bill Collection",
    "institutionCode": "999488",
    "institutionName": "Indulge MFB"
  },
  "narration": "Electricity purchase",
  "failureReason": null,
  "transactionDate": "2026-10-25T09:15:00+01:00",
  "updatedAt": "2026-10-25T09:15:00+01:00"
}

Errors

HTTP status	Body
400	`{"error":{"code":"30","message":"Invalid request"}}`
400	`{"error":{"code":"51","message":"Insufficient funds"}}`
401	`{"error":{"code":"63","message":"Missing, invalid or expired access token"}}`
403	`{"error":{"code":"63","message":"Operation not permitted"}}`
404	`{"error":{"code":"25","message":"Resource not found"}}`
409	`{"error":{"code":"94","message":"Reference has already been used; query the existing operation"}}`
429	`{"error":{"code":"91","message":"Rate limit exceeded"}}`
503	`{"error":{"code":"91","message":"Service unavailable"}}`

Reverse a bill payment

Request

POST https://api-dev.spay.ng/api/v1/bill-debits/bill-pos-0001/reversals
Authorization: Bearer <access-token>
Accept: application/json
Content-Type: application/json

{
  "reason": "Biller definitively confirmed no value was delivered"
}

curl -X POST 'https://api-dev.spay.ng/api/v1/bill-debits/bill-pos-0001/reversals' \
  -H "Authorization: Bearer $SPAY_ACCESS_TOKEN" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
  "reason": "Biller definitively confirmed no value was delivered"
}'

Response: 202 Accepted

{
  "reference": "bill-pos-0001-refund",
  "originalReference": "bill-pos-0001",
  "ownerAccountNumber": "8880000001",
  "type": "BILL_PAYMENT_REVERSAL",
  "mode": "CREDIT",
  "status": "PENDING",
  "reviewRequired": false,
  "amount": 2500.0,
  "feeAmount": 0.0,
  "currency": "NGN",
  "source": {
    "accountNumber": "8880000099",
    "accountName": "POS Bill Collection",
    "institutionCode": "999488",
    "institutionName": "Indulge MFB"
  },
  "beneficiary": {
    "accountNumber": "8880000001",
    "accountName": "Adunni Foods"
  },
  "narration": "Bill payment reversal",
  "failureReason": null,
  "transactionDate": "2026-10-25T09:15:00+01:00",
  "updatedAt": "2026-10-25T09:15:00+01:00"
}

Errors

HTTP status	Body
400	`{"error":{"code":"30","message":"Invalid request"}}`
401	`{"error":{"code":"63","message":"Missing, invalid or expired access token"}}`
403	`{"error":{"code":"63","message":"Operation not permitted"}}`
404	`{"error":{"code":"25","message":"Resource not found"}}`
503	`{"error":{"code":"91","message":"Service unavailable"}}`