P2G Use Case V1
- Kibuuka, Arnold
P2G Payments Use Cases
Web Sequence Diagram
API Specifications:
Bill_ID_Generation
Description | This is the API that is called by the Payments BB when the Govt Entity in turn calls its API for receiving biller’s ID against a registered consumer | |||||
Client | Govt Entity | |||||
Server | Aggregator | |||||
Method | POST | |||||
Request Parameters | Field | Type | M/O | Description | ||
RequestID | String (12) | M | Globally unique ID | |||
SourceBBID | String (12) | M | To identify the origination of the request. | |||
Bill Details |
|
|
| |||
Consumer Info | Object | M | JSON Array | |||
Consumer Name | String (6) | M | The customer’s name eligible to pay for the bill. | |||
Consumer Number | Integer (10) | M | The customer’s ID against the bill. | |||
Biller Info | Object | M | JSON Array | |||
Biller Name | String (10) | M | The biller’s name whose bill is to be paid. | |||
Biller Number | Integer (10) | M | The biller ID. | |||
Bill Amount and Date | Object | M | JSON Array | |||
Due Date | Epoch | M | The date at which the consumer needs to pay the bill. | |||
Amount before Due Date | Integer | M | Amount calculated on due date. | |||
| Amount after Due Date | Integer | M | Amount calculated after due date. | ||
Sample Request Body | { "RequestID": "915251236706", "SourceBBID": "467028349179", "Consumer Info": [ "Consumer Name ": "Sameul", "Consumer Number": "12345678910", ]
“Biller Info”: [ “Biller Name”: “Tax Payment”, “Biller Number”:”12345678910”,
]
“Bill Amount and Date”: [ “Due Date”: “04/17/23” “Amount Before Due Date”: “2550”, “Amount after Due Date”: “2570”,
]
} | |||||
| Field | Type | M/O | Description | ||
Response Parameters | ResponseCode | String (2) | M | 00 – Success 01 – Failure | ||
ResponseDescription | String (200) | M |
| |||
RequestID | String (12) | M | Echoed from Request | |||
Bill_ID | Integer (20) | C | This will be the unique bill ID. | |||
Sample Response Body (Success) | { "ResponseCode": "00", "ResponseDescription": "Request successfully received by Pay-BB", "RequestID": "915251236706", "SourceBBID": "467028349179", "Bill ID": "123456789101112" } | |||||
Sample Response Body (Failure) | { "ResponseCode": "01", "ResponseDescription": "Request not acknowledged by Pay- "RequestID": "915251236706", "SourceBBID": "467028349179", } | |||||
1.1.2.2 Bill_Inquiry_Request
Description | This is the API that is called by the Payer FI to receive bill inquiry from the Payments BB. | |||||
Client | Payer FI | |||||
Server | Payments BB | |||||
Method | GET | |||||
Request Parameters | Field | Type | M/O | Description | ||
RequestID | String (12) | M | Globally unique ID | |||
SourceBBID | String (12) | M | To identify the origination of the request. | |||
Bill ID | Integer (12) | M | Unique Customer ID | |||
Sample Request Body | { "RequestID": "915251236706", "SourceBBID": "467028349179", "Bill ID”: “123456789101112”,
} | |||||
| Field | Type | M/O | Description | ||
Response Parameters | ResponseCode | String (2) | M | 00 – Success 01 – Failure | ||
ResponseDescription | String (200) | M |
| |||
RequestID | String (12) | M | Echoed from Request | |||
Bill_Inquiry | Object | M | The relevant bill details including customer and biller name. amount with due date and after due date. | |||
Bill_ID | Integer (12) | M | Echoed from Request | |||
Biller_Name | String (10) | M | Biller Name | |||
Customer_Name | String (6) | M | Customer Name | |||
Due Date | Epoch | M |
| |||
Amount on Due Date | Integer | C | The amount at which the consumer needs to pay bill with due date. | |||
| Amount after Due Date | Integer | C | Amount calculated after due date. | ||
Sample Response Body (Success) | { "ResponseCode": "00", "ResponseDescription": "Request successfully received by Pay-BB",
"RequestID": "915251236706", “BillID”: “123456789101112”
“Bill_Inquiry”: [ “Biller Name”: “Tax Payment”, "Consumer Name ": "Sameul", “Due Date”: “04/17/23” “Amount Before Due Date”: “2550”,
]
} | |||||
Sample Response Body (Failure) | { "ResponseCode": "01", "ResponseDescription": "Request not acknowledged by Pay- "RequestID": "915251236706", } | |||||
1.1.2.3 Pay_Bill_Request
Description | This is the API that is called by the Payer to the Payer FI to process payment. | |||||
Client | Payer | |||||
Server | Payer FI | |||||
Method | Post | |||||
Request Parameters | Field | Type | M/O | Description | ||
RequestID | String (12) | M | Globally unique ID | |||
SourceBBID | String (12) | M | To identify the origination of the request. | |||
Bill ID | Integer (12) | M | Unique Customer ID | |||
Authorization | AN (6) | M | Client OTP/ MPIN to authorize account debit | |||
Sample Request Body | { "RequestID": "915251236706", "SourceBBID": "467028349179", "Bill ID”: “123456789101”, “Authorization”: 123456 } | |||||
| Field | Type | M/O | Description | ||
Response Parameters | ResponseCode | String (2) | M | 00 – Success 01 – Failure | ||
Bill Payment Status | String (200) | M | Describes whether the payment was successfully processed or not | |||
Request ID | String (12) | M | Echoed from Request | |||
Bill ID | Integer (12) | M | Echoed from Request | |||
Sample Response Body (Success) | { "ResponseCode": "00", "BillPaymentStatus": "Payment successful", "RequestID": "915251236706", “BillID”: “123456789101” } | |||||
Sample Response Body (Failure) | { "ResponseCode": "01", "BillPaymentStatus": "Payment unsuccessful” "RequestID": "915251236706", “BillID”: “123456789101112” } | |||||
1.1.2.4 Bill_Payment_Confirmation_Notification
Description | This is the API that is called by the Payer FI to the Payments BB upon successful payment. | |||||
Client | Payer FI | |||||
Server | Payments BB | |||||
Method | POST | |||||
Request Parameters | Field | Type | M/O | Description | ||
RequestID | String (12) | M | Globally unique ID | |||
SourceBBID | String (12) | M | To identify the origination of the request. | |||
Bill ID | Integer (12) | M | Unique Customer ID | |||
Bill Payment Status | String (200) | M |
| |||
Sample Request Body | { "RequestID": "915251236706", "SourceBBID": "467028349179", "Bill ID”: “123456789101112”, } | |||||
| Field | Type | M/O | Description | ||
ResponseCode | String (2) | M | 00 – Success 01 – Failure | |||
Response Description | String (200) | M |
| |||
Request ID | String (12) | M | Echoed from Request | |||
Bill ID | Integer (12) | M | Echoed from Request | |||
Sample Response Body (Success) | { "ResponseCode": "00", "ResponseDescription": "Request successfully received by Pay-BB", "RequestID": "915251236706", “BillID”: “123456789101112” } | |||||
Sample Response Body (Failure) | { "ResponseCode": "01", "ResponseDescription": "Request not acknowledge by Pay-BB” "RequestID": "915251236706", “BillID”: “123456789101112” } | |||||
1.1.2.5 Bill_Payment_Confirmation
Description | This is the API that is called by the Payments BB to the Govt Entity upon receiving payment. | |||||
Client | Payments BB | |||||
Server | Govt Entity | |||||
Method | PUT | |||||
Request Parameters | Field | Type | M/O | Description | ||
RequestID | String (12) | M | Globally unique ID | |||
SourceBBID | String (12) | M | To identify the origination of the request. | |||
Bill ID | Integer (12) | M | Unique Customer ID | |||
| Txn Ref ID | Integer (10) | M | Unique transaction id generated by the payments BB. | ||
| Bill Status |
|
|
| ||
Sample Request Body | { "RequestID": "915251236706", "SourceBBID": "467028349179", "BillID”: “123456789101112”, “TxnRefID”: “12345678910” “BillStatus”: “Bill Successfully Paid” } | |||||
| Field | Type | M/O | Description | ||
Response Parameters | ResponseCode | String (2) | M | 00 – Success 01 – Failure | ||
Response Description | String (200) | M |
| |||
Request ID | String (12) | M | Echoed from Request | |||
Bill ID | Integer (12) | M | Echoed from Request | |||
Sample Response Body (Success) | { "ResponseCode": "00", "ResponseDescription": "Request successfully received by Govt- Entity", "RequestID": "915251236706", “BillID”: “123456789101112” } | |||||
Sample Response Body (Failure) | { "ResponseCode": "01", "ResponseDescription": "Request not acknowledge by Govt-Entity” "RequestID": "915251236706", “BillID”: “123456789101112” } | |||||
Web Sequence Diagram Code
title P2G Payment Variation 1
participant Payer
participant Payer FI
participant PaymentsBB
participant GovtEntity
GovtEntity->PaymentsBB: 1. Bill ID Gen_Req (Bill ID & Details)
PaymentsBB->GovtEntity: 2. Bill ID Gen_Resp(Bill ID & Details)
GovtEntity-->Payer: 3. Sends Bill ID & Details
Payer->Payer FI: 4. Pay Bill_Req (Bill ID & Details)
Payer FI->PaymentsBB:5. Bill Details_Req (Amount Fetch)
PaymentsBB->Payer FI:6. Bill Details_Resp(Amount Fetch)
note over Payer FI: Apply Payment \nValidation Checks e.g: \n 1. Already paid \n 2. Expiry Check
Payer FI->Payer FI: Debits Payer A/C
note right of Payer FI: Logs Txn Success_Ref ID
Payer FI -> Payer: 7. Pay Bill_Resp (Bill ID & Status)
Payer FI->PaymentsBB: 8. Notifies Bill payment Success
PaymentsBB --> PaymentsBB: i. Generates Txn Ref \nii. Marks Bill as Paid
PaymentsBB->GovtEntity:9. Notify Bill Payment_Success(Ref ID)