LogoLogo
Give FeedbackGovStack Home
23Q4
23Q4
  • Payments
  • 1 Version History
  • 2 Description
  • 3 Terminology
  • 4 Key Digital Functionalities
  • 5 Cross-Cutting Requirements
  • 6 Functional Requirements
  • 7 Data Structures
  • 8 Service APIs
    • 8.1 Government to Person (G2P) payments
    • 8.2 Voucher Management APIs
    • 8.3 Person-to-Government APIs (P2G) Bill Payments
  • 9 Internal Workflows
  • 10 Other Resources
Powered by GitBook

Copyright © 2024

On this page

Was this helpful?

Export as PDF
  1. 8 Service APIs

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

Last updated 2 months ago

Was this helpful?

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.

8.3.2 billrInquiryResponse

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

8.3.3 markBillPayment

This API marks a bill as paid.

8.3.4 billerRtpReq

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

8.3.5 billerRtpReq

8.3.6 rtpStatusUpdate

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

8.3.7 rtpStatusUpdateResponse

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

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
400
Bad Request
application/json
post
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"
}

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
400
Bad Request
application/json
get
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"
}

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
400
Bad Request
application/json
post
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"
}

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
400
Bad Request
application/json
post
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"
}
  • GETRetrieve bill information.
  • POSTSend bill inquiry response.
  • POSTMark a specific bill as paid.
  • POSTUpdate Payments BB with the status of a Bill Payment Notification.
  • POSTUpdate the Biller on the RTP response.
  • GETInquire about the status of RTP.
  • POSTRTP Status Response.

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
400
Bad request.
application/json
post
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"
}

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
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"
}

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
400
Bad request.
application/json
get
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"
}