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

/bills/{billId}

Authorizations

Path parameters

billIdstring · max: 20required

ID of the specific Bill invoice

Query parameters

fieldsstring · enumrequired

Specific fields for inquiry

Options: inquiry

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

requestIdstring · max: 12

billIdstring · max: 20

Responses

application/json

application/json

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --url '/bills/{billId}?fields=inquiry' \
  --header 'X-CorrelationID: text' \
  --header 'Platform-TenantId: text' \
  --header 'PayerFI-Id: text' \
  --header 'Content-Type: application/json'

202

400

202

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

Accepted

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

/bills/{billId}

Authorizations

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

requestIdstring · max: 12

reasonstring

billIdstring · max: 20

codeinteger · enum

Options: 0, 1

billDetailsobject

Responses

application/json

application/json

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --request POST \
  --url '/bills/{billId}' \
  --header 'X-CorrelationID: text' \
  --header 'Platform-TenantId: text' \
  --header 'PayerFI-Id: text' \
  --header 'Content-Type: application/json' \
  --data '{"code":0,"billDetails":{}}'

200

400

200

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

Successful Response

8.3.3 markBillPayment

This API marks a bill as paid.

Mark a specific bill as paid.

post

/billTransferRequests

Authorizations

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

requestIDstring · max: 12

billIdstring · max: 20

PaymentReferenceIDstring · max: 16

Responses

application/json

application/json

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --request POST \
  --url '/billTransferRequests' \
  --header 'X-CorrelationID: text' \
  --header 'X-Platform-TenantId: text' \
  --header 'X-Payer FI-ID: text' \
  --header 'Content-Type: application/json'

202

400

202

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

Request Accepted

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

/billTransferRequests

Authorizations

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

requestIdstring · max: 12

billIdstring · max: 20

statusstring · enum

Options: ACK, RJC

rejectReasonstring · enum · max: 3

Options: Def, Dup, Und

Responses

application/json

application/json

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --request POST \
  --url '/billTransferRequests' \
  --header 'X-CorrelationID: text' \
  --header 'X-Platform-TenantId: text' \
  --header 'X-Payer FI-ID: text' \
  --header 'Content-Type: application/json' \
  --data '{"status":"ACK","rejectReason":"Def"}'

202

400

202

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

Request Accepted

8.3.5 billerRtpReq

Update the Biller on the RTP response.

post

/rtpUpdate

Authorizations

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

requestIdstring · max: 12

rtpIdinteger · max: 12

billIdstring · max: 30

rtpStatusstring · enum

Options: 00, 01

rejectReasonstring · enum · max: 10

Options: R, E, W

Responses

application/json

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --request POST \
  --url '/rtpUpdate' \
  --header 'X-CorrelationID: text' \
  --header 'X-Platform-TenantId: text' \
  --header 'X-billerId: text' \
  --header 'Content-Type: application/json' \
  --data '{"rtpStatus":"00","rejectReason":"R"}'

200

200

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

RTP Update Acknowledged

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

/transferRequests/{transferRequestId}

Authorizations

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

RequestIdstring · max: 12

rtpIdinteger

Responses

application/json

application/json

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --url '/transferRequests/{transferRequestId}' \
  --header 'X-CorrelationID: text' \
  --header 'X-Platform-TenantId: text' \
  --header 'X-billerId: text' \
  --header 'Content-Type: application/json'

202

400

202

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

Request accepted.

8.3.7 rtpStatusUpdateResponse

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

RTP Status Response.

post

/transferRequests/{transferRequestId}

Authorizations

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

rtpIdinteger

RequestIdstring · max: 12

PaymentReferenceIDstring · max: 20

lastUpdateDateinteger

requestStatusstring · enum

Options: COM, PND, EXP, CAN, RJC

Responses

application/json

application/json

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --request POST \
  --url '/transferRequests/{transferRequestId}' \
  --header 'X-CorrelationID: text' \
  --header 'X-Platform-TenantId: text' \
  --header 'X-billerId: text' \
  --header 'Content-Type: application/json' \
  --data '{"requestStatus":"COM"}'

202

400

202

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

Request accepted.