8.3 Person-to-Government APIs (P2G) Bill Payments

The Bill Payments APIs allow government entities to accept bill payments from persons on digital platforms like mobile money and vouchers.

8.3.1 billInquiryBiller

This API is called to inquire about bill details from a Bill Aggregator or Govt Entity.

Retrieve bill information.

get

Authorizations

PayerFIAuth

X-CorrelationIDstringRequired

Path parameters

billIdstring · max: 20Required

ID of the specific Bill invoice

Query parameters

fieldsstring · enumRequired

Specific fields for inquiry

Possible values:

Header parameters

X-CorrelationIDstring · max: 20Required

Globally unique requestId/ client correlation Id

Platform-TenantIdstring · max: 20Required

Tenant Id for Data scoping

PayerFI-Idstring · max: 20Required

Payer FI ID initiating the original bill inquiry/ payment sequence

Body

application/json

requestIdstring · max: 12Optional

billIdstring · max: 20Optional

Responses

202

Accepted

application/json

400

Bad Request

application/json

get

/bills/{billId}

HTTPcURLJavaScriptPython

GET /bills/{billId}?fields=inquiry HTTP/1.1
Host: 
X-CorrelationID: text
Platform-TenantId: text
PayerFI-Id: text
Content-Type: application/json
Accept: */*
Content-Length: 36

{
  "requestId": "text",
  "billId": "text"
}

{
  "responseCode": "text",
  "reason": "text",
  "requestId": "text"
}

8.3.2 billrInquiryResponse

The Payment BB updates the Bill Aggregator or government entity on the status of the Request to Pay.

Send bill inquiry response.

post

Authorizations

PayerFIAuth

X-CorrelationIDstringRequired

Header parameters

X-CorrelationIDstring · max: 20Required

Globally unique requestId/ client correlation Id

Platform-TenantIdstring · max: 20Required

Tenant Id for Data scoping

PayerFI-Idstring · max: 20Required

Payer FI ID initiating the original bill inquiry/ payment sequence

Body

application/json

requestIdstring · max: 12Optional

codeinteger · enumOptionalPossible values:

reasonstringOptional

billIdstring · max: 20Optional

Responses

200

Successful Response

application/json

400

Bad Request

application/json

post

/bills/{billId}

HTTPcURLJavaScriptPython

POST /bills/{billId} HTTP/1.1
Host: 
X-CorrelationID: text
Platform-TenantId: text
PayerFI-Id: text
Content-Type: application/json
Accept: */*
Content-Length: 190

{
  "requestId": "text",
  "code": 0,
  "reason": "text",
  "billId": "text",
  "billDetails": {
    "billerId": "text",
    "billerName": "text",
    "billStatus": "text",
    "dueDate": 1,
    "amountonDueDate": 1,
    "amountAfterDueDate": 1
  }
}

{
  "responseCode": "text",
  "reason": "text",
  "requestID": "text"
}

8.3.3 markBillPayment

This API marks a bill as paid.

Mark a specific bill as paid.

post

Authorizations

PaymentsBBAuth

X-CorrelationIDstringRequired

Header parameters

X-CorrelationIDstring · max: 20Required

Globally unique requestId/ client correlation Id

X-Platform-TenantIdstring · max: 20Required

Tenant Id for Data scoping

X-Payer FI-IDstring · max: 20Required

Payer FI ID initiating the original bill inquiry/ payment sequence

Body

application/json

requestIDstring · max: 12Optional

billIdstring · max: 20Optional

PaymentReferenceIDstring · max: 16Optional

Responses

202

Request Accepted

application/json

400

Bad Request

application/json

post

/billTransferRequests

HTTPcURLJavaScriptPython

POST /billTransferRequests HTTP/1.1
Host: 
X-CorrelationID: text
X-Platform-TenantId: text
X-Payer FI-ID: text
Content-Type: application/json
Accept: */*
Content-Length: 64

{
  "requestID": "text",
  "billId": "text",
  "PaymentReferenceID": "text"
}

{
  "responseCode": "text",
  "reason": "text",
  "requestID": "text"
}

8.3.4 billerRtpReq

The Bill Aggregator or Govt Entity initiates a “Request to Pay” (RTP) through this API.

Update Payments BB with the status of a Bill Payment Notification.

post

Authorizations

BillerAuth

X-CorrelationIDstringRequired

Header parameters

X-CorrelationIDstring · max: 20Required

Globally unique requestId/ client correlation Id

X-Platform-TenantIdstring · max: 20Required

Tenant Id for Data scoping

X-Payer FI-IDstring · max: 20Required

Payer FI ID initiating the original bill inquiry/ payment sequence

Body

application/json

requestIdstring · max: 12Optional

billIdstring · max: 20Optional

statusstring · enumOptionalPossible values:

rejectReasonstring · enum · max: 3OptionalPossible values:

Responses

202

Request Accepted

application/json

400

Bad Request

application/json

post

/billTransferRequests

HTTPcURLJavaScriptPython

POST /billTransferRequests HTTP/1.1
Host: 
X-CorrelationID: text
X-Platform-TenantId: text
X-Payer FI-ID: text
Content-Type: application/json
Accept: */*
Content-Length: 72

{
  "requestId": "text",
  "billId": "text",
  "status": "ACK",
  "rejectReason": "Def"
}

{
  "responseCode": "text",
  "reason": "text",
  "requestID": "text"
}

8.3.5 billerRtpReq

Update the Biller on the RTP response.

post

Authorizations

PaymentsBBAuth

X-CorrelationIDstringRequired

Header parameters

X-CorrelationIDstring · max: 20Required

Globally unique requestId/ client correlation Id

X-Platform-TenantIdstring · max: 20Required

Tenant Id for Data scoping

X-billerIdstring · max: 20Required

ID of the institution initiating the RTP

Body

application/json

requestIdstring · max: 12Optional

rtpIdinteger · max: 12Optional

billIdstring · max: 30Optional

rtpStatusstring · enumOptionalPossible values:

rejectReasonstring · enum · max: 10OptionalPossible values:

Responses

200

RTP Update Acknowledged

application/json

post

/rtpUpdate

HTTPcURLJavaScriptPython

POST /rtpUpdate HTTP/1.1
Host: 
X-CorrelationID: text
X-Platform-TenantId: text
X-billerId: text
Content-Type: application/json
Accept: */*
Content-Length: 82

{
  "requestId": "text",
  "rtpId": 1,
  "billId": "text",
  "rtpStatus": "00",
  "rejectReason": "R"
}

200

RTP Update Acknowledged

{
  "responseCode": "text",
  "responseDescription": "text",
  "requestID": "text"
}

8.3.6 rtpStatusUpdate

This API allows the Biller or Aggregator to inquire about the status of its RTP.

Inquire about the status of RTP.

get

Authorizations

PaymentsBBAuth

X-CorrelationIDstringRequired

Path parameters

transferRequestIdstringRequired

Transfer request ID

Header parameters

X-CorrelationIDstring · max: 20Required

Globally unique requestId/ client correlation Id

X-Platform-TenantIdstring · max: 20Required

Tenant Id for Data scoping

X-billerIdstring · max: 20Required

ID of the institution requesting the transaction Update

Body

application/json

RequestIdstring · max: 12Optional

rtpIdintegerOptional

Responses

202

Request accepted.

application/json

400

Bad request.

application/json

get

/transferRequests/{transferRequestId}

HTTPcURLJavaScriptPython

GET /transferRequests/{transferRequestId} HTTP/1.1
Host: 
X-CorrelationID: text
X-Platform-TenantId: text
X-billerId: text
Content-Type: application/json
Accept: */*
Content-Length: 30

{
  "RequestId": "text",
  "rtpId": 1
}

{
  "responseCode": "text",
  "reason": "text",
  "requestID": "text"
}

8.3.7 rtpStatusUpdateResponse

This API allows the Biller or Aggregator to receive the status of its RTP.

RTP Status Response.

post

Authorizations

PaymentsBBAuth

X-CorrelationIDstringRequired

Path parameters

transferRequestIdstringRequired

Transfer request ID

Header parameters

X-CorrelationIDstring · max: 20Required

Globally unique requestId/ client correlation Id

X-Platform-TenantIdstring · max: 20Required

Tenant Id for Data scoping

X-billerIdstring · max: 20Required

ID of the institution requesting the transaction Update

Body

application/json

rtpIdintegerOptional

RequestIdstring · max: 12Optional

requestStatusstring · enumOptionalPossible values:

PaymentReferenceIDstring · max: 20Optional

lastUpdateDateintegerOptional

Responses

202

Request accepted.

application/json

400

Bad request.

application/json

post

/transferRequests/{transferRequestId}

HTTPcURLJavaScriptPython

POST /transferRequests/{transferRequestId} HTTP/1.1
Host: 
X-CorrelationID: text
X-Platform-TenantId: text
X-billerId: text
Content-Type: application/json
Accept: */*
Content-Length: 99

{
  "rtpId": 1,
  "RequestId": "text",
  "requestStatus": "COM",
  "PaymentReferenceID": "text",
  "lastUpdateDate": 1
}

{
  "ResponseCode": "text",
  "reason": "text",
  "requestID": "text"
}