Skip to main content

​
Billing & Payment Schemas

API endpoints for processing payments and establishing billing agreements.

​
Endpoints

MethodEndpointDescription
POST/v1/billing/intentSend billing intent to establish agreement
POST/v1/customer/billBill customer using agreement phrase

​
POST /v1/billing/intent

Send billing intent to customers via their banks to establish billing agreements.

​
Request Body

{
  "lookupPhrases": ["string"],
  "currency": "string",
  "description": "string"
}

​
Request Schema

FieldTypeRequiredDescription
lookupPhrasesstring[]YesCustomer lookup phrases
currencystringYesCurrency code (e.g., “NGN”)
descriptionstringYesDescription of billing agreement

​
Response Schema

[
  {
    "statusCode": 200,
    "success": true,
    "message": "Billing intent sent successfully",
    "lookupPhrase": "string",
    "entityId": "string"
  }
]

​
Response Fields

FieldTypeDescription
lookupPhrasestringCustomer lookup phrase used
entityIdstringMerchant entity identifier

​
POST /v1/customer/bill

Bill customers using established agreement phrases.

​
Request Body

{
  "agreementPhrases": ["string"],
  "amount": 1500,
  "currency": "string",
  "description": "string"
}

​
Request Schema

FieldTypeRequiredDescription
agreementPhrasesstring[]YesCustomer agreement phrases
amountnumberYesAmount to bill
currencystringYesCurrency code
descriptionstringYesPayment description

​
Response Schema

[
  {
    "statusCode": 201,
    "success": true,
    "message": "Customer billed successfully",
    "reference": "string",
    "phrase": "string",
    "entityId": "string"
  }
]

​
Response Fields

FieldTypeDescription
referencestringTransaction reference
phrasestringAgreement Phrase used
entityIdstringMerchant entity identifier

​
Error Responses

​
400 Bad Request

{
  "statusCode": 400,
  "success": false,
  "message": "Invalid request parameters"
}

​
403 Forbidden

{
  "statusCode": 403,
  "success": false,
  "message": "Customer has not approved billing"
}