Payment Bill

We’ve designed bills for simplicity and compatibility to take advantage of different use-cases, either a regular payment bill (Transaction Bills) or a dynamic (non-transactional Bills).

By default, all payment bills are transactional (i.e. they are unique and can receive value).

Use Case

On your store-front, you want each payment unique to each customer, then our regular payment bill (transactional bill) will be used. In a case where you want a reusable payment link to request money from your customers, then our dynamic payment bills (non-transactional) is best suited.

Regular (Transaction Bills)

Regular payment bills are unique with non-reusable payment references, and suitable for one-time payments.

POST {{BASE_URL}}}/v1/checkout

{ "amount": 1000, "email": "[e-mail]" }

Request Body

Name	Type	Description
amount*	Number	Bill Number
email*	String	Recipient email address

201: Created

{
    "success": true,
    "data": {
        "outstanding": 0,
        "amountPaid": 0,
        "split": false,
        "transactionCharge": 0,
        "type": "regular",
        "expiry": false,
        "queuedForRetry": false,
        "status": "pending",
        "message": [],
        "settled": false,
        "retries": 0,
        "virtual": false,
        "_id": "xxx",
        "deleted": false,
        "merchantId": "xxx",
        "email": "[e-mail]",
        "amount": 1000,
        "bearer": "xxx",
        "principalAccount": "xxx",
        "callback": {},
        "paymentRef": "xxx",
        "qrCode": "xxx.png",
        "originalBillAmount": 1000,
        "createdAt": "2021-11-04T12:16:25.477Z",
        "updatedAt": "2021-11-04T12:16:25.477Z",
        "__v": 0
    }
}

Dynamic (Non-Transactional Bills)

Dynamic payment bills are unique with reusable payment references, and suitable for accepting multiple payments.

Please note: every dynamic payment reference generates a unique payment reference at the time of payment.

POST {{BASE_URL}}/v1/checkout

{ "amount": 1000, "email": "[e-mail]", "type": "dynamic" }

Request Body

Name	Type	Description
amount*	Number	Bill Amount
email*	String	Recipients email address
type	String	Bill type. Default to regular

201: Created

{
    "success": true,
    "data": {
        "expiry": false,
        "type": "dynamic",
        "isFlexible": true,
        "status": "active",
        "split": false,
        "_id": "xxx",
        "deleted": false,
        "merchantId": "xxx",
        "amount": 1000,
        "reference": "xxx",
        "qrCode": "xxx.png",
        "createdAt": "2021-11-04T12:17:25.785Z",
        "updatedAt": "2021-11-04T12:17:25.785Z",
        "__v": 0
    }
}

Payment Bill Properties

Properties	Description	Type	Required
amount	Bill amount	Number	True
duration	Expiry time eg. ‘1h’ for 1 hour and ‘1d’ for 1 day, etc	String	False
email	Email address of the customer	String	True
expiry	Determine if bill should expire	String	False
externalRef	Custom reference	String	False
redirectURL	URL to redirect to from the checkout modal after complete payment	String	False
narration	Bill narration	String	False
spilt	Determine whether to share value between multiple subaccounts	Boolean	False
subaccounts	Array of objects containing account referen HD ce and amount/percentage for split sharing.	Array<Accounts>	False
callbackURL	Callback URL to receive webhooks on.	String	False
qrcode	Enable QRCode. Dafaults true.	Boolean	False
virtual	Enables virtual account. Dafault false	Boolean	False
resolvable	Account reference that resolves the virtual account. EX: “principal”	String	False
isFlexible	Allow any amount. Only applicable for dynamic bills. Defaults false	Boolean	False
type	Bill type. Defaults regular	String: "regular", "dynamic"	False
maximumAmount	Maximum payable amount at once for dynamic payment bills.	Number	False
minimumAmount	Minimum payable amount at once for dynamic payment bills.	Number	False
targetAmount	Maximum/Accumulated amount before disabling the bill.	Number	False

Re-query Payment

GET {{BASE_URL}}/v1/checkout/requery/{{paymentRef}}

200: OK

{
    "success": false,
    "data": {
        "outstanding": 0,
        "amountPaid": 0,
        "split": true,
        "transactionCharge": 0,
        "type": "regular",
        "expiry": false,
        "queuedForRetry": false,
        "status": "pending",
        "message": [],
        "settled": false,
        "retries": 0,
        "virtual": false,
        "deleted": false,
        "_id": "xxx",
        "merchantId": "xxx",
        "email": "[e-mail]",
        "amount": 1000,
        "subaccounts": [
            {
                "_id": "xxx",
                "accountRef": "xxx",
                "amount": 100,
                "accountNumber": "xxx"
            }
        ],
        "bearer": "xxx",
        "principalAccount": {
            "_id": "xxx",
            "accountNumber": "xxx",
            "accountRef": "xxx",
            "percentage": 0.1
        },
        "paymentRef": "xxx",
        "createdAt": "2021-03-16T02:47:11.958Z",
        "updatedAt": "2021-03-16T02:47:11.958Z",
        "__v": 0
    }
}

Update Payment Bills

Example

PUT {{BASE_URL}}/v1/checkout/{{paymentRef}}

{ "amount": 30000, "email": "[e-mail]", "split": true, "subaccounts": [ { "accountRef": " xxx", "amount": 100 } ] }

200: OK

{
    "success": true,
    "data": {
        "split": true,
        "transactionCharge": 0,
        "type": "regular",
        "expiry": false,
        "queuedForRetry": false,
        "status": "pending",
        "message": [],
        "settled": false,
        "retries": 0,
        "deleted": false,
        "_id": "xxx",
        "merchantId": "xxx",
        "email": "[e-mail]",
        "amount": 30000,
        "subaccounts": [
            {
                "_id": "xxx",
                "accountRef": "xxx",
                "amount": 100,
                "accountNumber": "xxx"
            }
        ],
        "bearer": "xxx",
        "principalAccount": {
            "_id": "xxx",
            "accountNumber": "xxx",
            "accountRef": "xxx",
            "percentage": 0.015
        },
        "paymentRef": "xxx",
        "createdAt": "2021-03-16T11:15:07.066Z",
        "updatedAt": "2021-03-16T12:28:11.272Z",
        "__v": 0
    }
}