All SpecificationsGovStack Website

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
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
requestIdstring · max: 12Optional
billIdstring · max: 20Optional
Responses
202

Accepted

application/json
get
/bills/{billId}
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
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: 12Optional
codeinteger · enumOptionalPossible values:
reasonstringOptional
billIdstring · max: 20Optional
Responses
200

Successful Response

application/json
post
/bills/{billId}
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
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: 12Optional
billIdstring · max: 20Optional
PaymentReferenceIDstring · max: 16Optional
Responses
202

Request Accepted

application/json
post
/billTransferRequests
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
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: 12Optional
billIdstring · max: 20Optional
statusstring · enumOptionalPossible values:
rejectReasonstring · enum · max: 3OptionalPossible values:
Responses
202

Request Accepted

application/json
post
/billTransferRequests
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
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: 12Optional
rtpIdinteger · max: 12Optional
billIdstring · max: 30Optional
rtpStatusstring · enumOptionalPossible values:
rejectReasonstring · enum · max: 10OptionalPossible values:
Responses
200

RTP Update Acknowledged

application/json
post
/rtpUpdate
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
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: 12Optional
rtpIdintegerOptional
Responses
202

Request accepted.

application/json
get
/transferRequests/{transferRequestId}
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
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
rtpIdintegerOptional
RequestIdstring · max: 12Optional
requestStatusstring · enumOptionalPossible values:
PaymentReferenceIDstring · max: 20Optional
lastUpdateDateintegerOptional
Responses
202

Request accepted.

application/json
post
/transferRequests/{transferRequestId}
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"
}

Last updated

Was this helpful?