THE UNITED REPUBLIC OF

TANZANIA

PAYMENT POSTING APPLICATION

PROGRAMMING INTERFACE V1.0

July, 2019
Contents
1. PREREQUISITES.............................................................................................................................1
2. REQUEST HEADER........................................................................................................................2
3. PAYMENT VOUCHER POSTING FLOW.....................................................................................2
Payment Voucher Submission Request –MUSEPvSubReq..................................................................3
3.1 MESSAGE DETAIL PARAMETER DEFINITION......................................................................4
3.2 Voucher Submission Request Acknowledgement – MUSEPvSubReqAck.............................5
3.3 Voucher Submission Response–MUSEPvSubResp.................................................................5
4. BULKY PAYMENT POSTING FLOW...........................................................................................7
4.1 Bulky Payment Submission Request –MUSEBPSubReq...............................................................7
4.2 MESSAGE DETAIL PARAMETER DEFINITION......................................................................8
4.3 Bulky Payment Submission Request Acknowledgement – MUSEBPSubReqAck...............10
4.4 Bulky Payment Submission Response–MUSEBPSubResp........................................................10
5 Digital Signature Security.................................................................................................................12
5.1 Overview........................................................................................................................................12
5.2 Digital Signature............................................................................................................................13
5.3 Format of Digital Signature...........................................................................................................13

ii | P a g e
Document Description

Document Name Payment Posting Application Programming

Interface (API)

Owner Government of Tanzania

Document Type MUSE – Public institution Integration

Document version Control

Version Date Change Description

1.0 20-03-2022 Baseline initial version created.
iii| P a g e
 1. PREREQUISITES
i. Network Connection to Finance Bus Integrating institution is supposed to establish
secure Virtual Private Network (VPN) connection with Finance Bus hosted at
Government Data center.
ii. Payment System Integrating institution must have a working or complete developed
system that is ready for integration testing with MUSE
iii. Call Back URLs - Integrating institution must provide the following API URLs for
receiving responses from MUSE into :-
 Payment Voucher Posting Notification
 Bulky Payments Posting Notifications
 Unapplied Payments Notification
iv. Digital Certificates - Integrating institution must share her public certificate and
obtain MUSE public certificate to be used in verification of all messages exchanged
between her payments originating system and MUSE.
v. MUSE End Points
 Payment Voucher Posting:
 http://<FBIP>:<port>/api/MUSE/postpv
 Bulky Payments Posting:
 http://<FBIP>:<port>/api/MUSE/postbulky

NOTE:
Testing certificates may be provided by MUSE.

1|Page
 2. REQUEST HEADER

The following parameters should be included in HTTP header when sending request
to MUSE
Parameter Values/Description
Content-Type Application/JSON
MUSE-Com default.sp.in
Institution Code Will be given during the integration

3. PAYMENT VOUCHER POSTING FLOW

vi. Integrating institution Payment originating system composes payment voucher

submission request as per MUSEPvSubReq JSON format and submit (single
Payment Voucher or multiple Payment Vouchers at once) to Finance Bus
vii. Finance Bus relays the message to MUSE and send back acknowledgement as per
MUSEPvSubReqAck JSON
viii. MUSE receive the payment voucher request, post the PV to its incoming PV queue
for processing.
ix. MUSE, compose the Payment voucher response as per MUSEPVPostSubReq JSON
format and send the result to a Finance Bus
x. The Finance Bus relays the Response from MUSE to payment originating system

Payment Voucher
Posting Flow

Pv submission request Pv submission request

Payment Originating Pv submission ACK

Finance Bus
Systen
MUSE

Pv Posting ACK Pv Posting ACK

Payment Voucher Submission Request –MUSEPvSubReq

2|Page
"message": {
"messageHeader": {
"sender": "ILMS",
"receiver": "MUSE",
"msgId": "2021080916580405",
"messageType": "Payment",
"paymentType": "Payment Voucher"
},
"paymentVoucher": {
ReferenceNo: "12367HTS54",
Narration: "Malipo ya Chakula kwa wanafunzi",
PayeeCode: "111-222-333",
SBC:’103’,
Payeename: " Higher Education Students Loans Board ",
PayeeBankAccount: "01J2000000000",
PayeeBankName: "CRDB",
PayeeAccountName: "HESLB Suspense AC",
PayeeBIC: "CORTZTZ",
PayerBankAccount: "01J8900000000",
PayerBankName: "CRDB",
PaymentDesc: "Malipo Batch 1",
Amount: "1,000,000.00",
Currency: "TZS",
ExchangeRate: "1",
ApplyDate: "2022-03-20 00:00:00.000"
ControlNumber: "N/A",
UnappliedAccount: "PayerBankAccount",
NetOperationalAmount: "",
NetBaseAmount: "",
InstitutionLevel: "",
Level1Code: "",
Level1Desc: "",
}
"voucherDetails": [
{
crGlAccount:"046|7001|0TR99|...|103|...|1|00000|10A|22120278",
crGlAccountDesc: “”,
DrGlAccount:" 046|7001|0TR99|...|103|...|1|00000|10A|33181102",
drGlAccountDesc:"desc”,
Amount: “500,000.00”,
},
{
crGlAccount:"046|7001|0TR99|...|103|...|1|00000|10A|22120279",
crGlAccountDesc: “”,
DrGlAccount:" 046|7001|0TR99|...|103|...|1|00000|10A|33181102",
drGlAccountDesc:"desc”,
Amount: “500,000.00”,

},

//...
]
},
"digitalSignature":
"Ef4tR3CW7PjkjgfwiejiAfZXIWjbdqTK1f+o5UfX/tmkR6P7IlFnkOfmjWoCwHoiM3qq
qNgmBbbW4yaSMG+XAKwECu6bw1DqEz46ouMhoSkhHQpJ9eWKCzgTIiXezpCZ/
NeHyR0TswoqQrtQQ9nbQe/
sqbVFe8GNwypCAKUJLsNjmzMgwj04WSGk2hW3tcQW20oB0nfsekdKLKKWYMltlis9KrNi
Yzp+QSkc31TsKCBFI/kADUcQ2cAA0y0AaN4N3Sk1Ysq8nd4kZywKOsE/
ItOvptfuxrM0rTe9s4SsRp5Revf8RenapxuLmMGxLgC2pAO4DOiaxGzuAr1XXTM85Q=="
}

3|Page
3.1 MESSAGE DETAIL PARAMETER DEFINITION

MUSEPvSubReq Data Type MUSE Bill Submission Request –

Used to Submit Payment Voucher to MUSE

messageHeader Payment voucher Header Information

Sender String(8) Mandatory Payment originating Institution System
Receiver String(8) Mandatory Payment Processing System (MUSE)

msgId String(20) This is message reference No

Mandatory

messageType String(100) Mandatory Indicate the type of message

paymentType String(100) Mandatory Indicate the type of message

Reference No Number(10) Mandatory Payment reference No

Narration: String(100) Mandatory Payment Naration

SBC String(5) Mandatory Sub budget Class. The list of SBC will be
shared as Appendix
PayeeCode: String(20) Mandatory Payee Identification Number e.g TIN or
Checkno
Payeename String(100) Mandatory Payee Name

PayeeBankAccount String(20) Mandatory Payee Bank Account Number

PayeeBankName String(100) Mandatory Payee Bank Name
PayeeAccountName String(100) Mandatory Payee Bank Account Name

PayeeAddress String(50) Optional Payee Address

PayeeBIC String(20) Mandatory Payee Bank Identification Code

PayerBankAccount String(100) Mandatory Payer Bank Account Name

PayerBankName String(100) Mandatory Payer Bank Name

PayerBIC String(20) Mandatory Payer Bank Account Identification Code

PaymentDesc String(100) Mandatory Payment Description

Amount Double Mandatory Amount to be paid in Base Currency

Currency String(5) Mandatory Currency

ExchangeRate Double Mandatory Transaction Exchange rate

ApplyDate Date/Time Mandatory Payment Originating Date with format

YYYY-MM-DDTHH24:MI:SS (2017-03-

4|Page
 25T14:30:12). Accepts today dates only.
ControlNumber String(20) Optional Transaction control number if exists

UnappliedAccount String(20) Mandatory Account to return funds incase of unapplied

CrGlAccount String(200) Optional Credit GL Account

CrGlAccountDesc String(200) Optional Credit Gl Account Description
DrGlAccount Double Optional Debit Gl Account
DrGlAccountDesc String(200) Optional Debit Gl Account description
ItemAmount Double Optional Item amount

3.2 Voucher Submission Request Acknowledgement –

MUSEPvSubReqAck

{
trxStsCode: 7101
}
NOTE:
Transaction Status Code (TrxStsCode)- Refer Appendix I for codes definition. If
several will be separated by semicolon e.g. (7242;7201).

3.3 Voucher Submission Response–MUSEPvSubResp

3.3.1 Success Response

{
"message": {
"messageHeader": {
"sender": "MUSE",
"receiver": "ILMS",
"msgId": "FBUS20210722215426884",
"messageType": "ACK",
"paymentType": "PV"
},
"messageSummary": {
"orgMsgId": "20210722205348",
"createdAt": "2021-07-22T21:54:26.915",
"status": "ACCEPTED",
"statusDesc": "Accepted successfully"
“PVNo”:”ILMS0000PV00001”
}
},
"digitalSignature":
"ixIt2a7tcFiolZzPvxl0GqRz7B8GcqDlppyj0vKvKXyMXnQM4ofXTjqWRnELob5Tge5nOi4xkiAb0PXdV2wjg
QxMgDwFifNXfxqV1XkHySXi8JDuMrWuxd+gKvbLuZXpwYgyJxXUSrdCPJS4gIUQE2rzMwAgSmks4awd
5mNQQ/94x+W0JuHGkr677O4zwLSi2XzFtAsVKj/3Crc/

5|Page
 fdkG9NaEOQ1gVuIMeW+ciCNXNL4Z86QVOlUnKMmp602nY2ZUTqDE6uWklsb6L/eov3HJlIYNo/
+VaqZ/2LT9djqNA3iH4IhQfWW8uz7PIF9OsKhFY0oVedIyqNIxCVapMY3RKg=="}

3.3.2 Failure Response

{
"message": {
"messageHeader": {
"sender": "FBUS",
"receiver": "ILMS",
"msgId": "FBUS20210722215426884",
"messageType": "ACK",
"paymentType": "PV"
},
"messageSummary": {
"orgMsgId": "20210722205348",
"createdAt": "2021-07-22T21:54:26.915",
"status": "Rejected",
"statusDesc": "Payee does not exist"

}
},
"digitalSignature":
"ixIt2a7tcFiolZzPvxl0GqRz7B8GcqDlppyj0vKvKXyMXnQM4ofXTjqWRnELob5Tge5nOi4xkiAb0PXdV2wjg
QxMgDwFifNXfxqV1XkHySXi8JDuMrWuxd+gKvbLuZXpwYgyJxXUSrdCPJS4gIUQE2rzMwAgSmks4awd
5mNQQ/94x+W0JuHGkr677O4zwLSi2XzFtAsVKj/3Crc/
fdkG9NaEOQ1gVuIMeW+ciCNXNL4Z86QVOlUnKMmp602nY2ZUTqDE6uWklsb6L/eov3HJlIYNo/
+VaqZ/2LT9djqNA3iH4IhQfWW8uz7PIF9OsKhFY0oVedIyqNIxCVapMY3RKg=="}

3.3.3 Voucher/BulkyPaymentBatch Cancellation Notification

{
"message": {
"messageHeader": {
"sender": "MUSE",
"receiver": "ILMS",
"msgId": "FBUS20210722215426884",
"messageType": "ACK",
"paymentType": "PV"
},
"messageSummary": {
"orgMsgId": "20210722205348",
"createdAt": "2021-07-22T21:54:26.915",
"status": "Cancelled",
"statusDesc": "Cancellation on request"
“PVNo”:”ILMS0000PV00001”
}
},
"digitalSignature":
"ixIt2a7tcFiolZzPvxl0GqRz7B8GcqDlppyj0vKvKXyMXnQM4ofXTjqWRnELob5Tge5nOi4xkiAb0PXdV2wjg
QxMgDwFifNXfxqV1XkHySXi8JDuMrWuxd+gKvbLuZXpwYgyJxXUSrdCPJS4gIUQE2rzMwAgSmks4awd
5mNQQ/94x+W0JuHGkr677O4zwLSi2XzFtAsVKj/3Crc/

6|Page
 fdkG9NaEOQ1gVuIMeW+ciCNXNL4Z86QVOlUnKMmp602nY2ZUTqDE6uWklsb6L/eov3HJlIYNo/
+VaqZ/2LT9djqNA3iH4IhQfWW8uz7PIF9OsKhFY0oVedIyqNIxCVapMY3RKg=="}

4. BULKY PAYMENT POSTING FLOW

i. Integrating institution Payment originating system composes Bulky payment

submission request as per MUSEBPSubReq xml format and submit (single Bulky
Payment Batch or multiple Bulky Payment Batches at once) to Finance Bus
ii. Finance Bus relays the message to MUSE and send back acknowledgement as per
MUSEBPSubReqAck
iii. MUSE receive the Bulky Payment request, post the Bulky payment to its incoming
Bulky Payment queue for processing.
iv. MUSE, compose the Bulky Payment response as per MUSEBPPostSubReq xml
format and send the result to a Finance Bus
v. The Finance Bus relays the Response from MUSE to payment originating system

Bulky Payment
Posting Flow

BP submission request BP submission request

BP submission ACK
Payment Originating Finance Bus
Systen

BP Posting ACK BP Posting ACK

MUSE

4.1 Bulky Payment Submission Request –MUSEBPSubReq

"message": {
"messageHeader": {
"sender": "ILMS",
"receiver": "MUSE",
"msgId": "2021080916580405",
"messageType": "Bulky Payment Posting",

7|Page
 "paymentType": "Bulky Payment"
},
"PaymentBatch": {
“Institututioncode”:”ILMS”
ReferenceNo: "12367HTS52",
PaymentDesc: "Loan Refund",
TotalAmount: "2,000,000.00",
NoofTransaction: "100",
ApplyDate: "2022-03-20 00:00:00.000",

"PayList": [
{

PayeeCode: "20210722205348",
Payeename: "Innocent Anthony",
PayeeAccountNumber: "01J2008000000",
PayeeAccountName: "Innocent Anthony",
PayeeBankName: "CRDB",
PayeeBankBic: "CORTZTZ",
Amount: 100,000.00,
},
//...
]

},
"digitalSignature":
"Ef4tR3CW7PjkjgfwiejiAfZXIWjbdqTK1f+o5UfX/tmkR6P7IlFnkOfmjWoCwHoiM3qq
qNgmBbbW4yaSMG+XAKwECu6bw1DqEz46ouMhoSkhHQpJ9eWKCzgTIiXezpCZ/
NeHyR0TswoqQrtQQ9nbQe/
sqbVFe8GNwypCAKUJLsNjmzMgwj04WSGk2hW3tcQW20oB0nfsekdKLKKWYMltlis9KrNi
Yzp+QSkc31TsKCBFI/kADUcQ2cAA0y0AaN4N3Sk1Ysq8nd4kZywKOsE/
ItOvptfuxrM0rTe9s4SsRp5Revf8RenapxuLmMGxLgC2pAO4DOiaxGzuAr1XXTM85Q=="
}

4.2 MESSAGE DETAIL PARAMETER DEFINITION

MUSEPvSubReq Data Type MUSE Bill Submission Request –

Used to Submit Payment Voucher to MUSE

MessageHeader Payment voucher Header Information

Sender String(8) Mandatory Payment originating Institution System
Receiver String(8) Mandatory Payment Processing System (MUSE)

MsgId String(20) This is message reference No

Mandatory

MessageType String(100) Mandatory Indicate the type of message

PaymentType String(100) Mandatory Indicate the type of message

8|Page
Reference No Number(10) Mandatory Payment reference No
Narration: String(100) Mandatory Payment Naration

PayeeCode: String(20) Mandatory Payee Identification Number e.g TIN or

Checkno
Payeename String(100) Mandatory Payee Name

PayeeBankAccount String(20) Mandatory Payee Bank Account Number

PayeeBankName String(100) Mandatory Payee Bank Name
PayeeAccountName String(100) Mandatory Payee Bank Account Name

PayeeAddress String(50) Optional Payee Address

PayeeBIC String(20) Mandatory Payee Bank Identification Code

PayerBankAccount String(100) Mandatory Payer Bank Account Name

PayerBankName String(100) Mandatory Payer Bank Name

PayerBIC String(20) Mandatory Payer Bank Account Identification Code

PaymentDesc String(100) Mandatory Payment Description

Amount Double Mandatory Amount to be paid in Operational Currency

Currency String(5) Mandatory Currency

ExchangeRate Double Mandatory Transaction Exchange rate

ApplyDate Date/Time Mandatory Payment Originating Date with format

YYYY-MM-DDTHH24:MI:SS (2017-03-
25T14:30:12). Accepts today dates only.
ControlNumber String(20) Optional Transaction control number if exists

UnappliedAccount String(20) Mandatory Account to return funds incase of unapplied

CrGlAccount String(200) Optional Credit GL Account

CrGlAccountDesc String(200) Optional Credit Gl Account Description
DrGlAccount Double Optional Debit Gl Account
DrGlAccountDesc String(200) Optional Debit Gl Account description
ItemAmount Double Optional Item amount

4.3 Bulky Payment Submission Request Acknowledgement –

MUSEBPSubReqAck

{
trxStsCode: 7101

9|Page
}
NOTE:
Transaction Status Code (TrxStsCode)- Refer Appendix I for codes definition. If
several will be separated by semicolon e.g. (7242;7201).

4.4 Bulky Payment Submission Response–MUSEBPSubResp

4.4.1 Success Response

{
"message": {
"messageHeader": {
"sender": "FBUS",
"receiver": "ILMS",
"msgId": "FBUS20210722215426884",
"messageType": "ACK",
"paymentType": "BP"
},
"messageSummary": {
"orgMsgId": "20210722205348",
"createdAt": "2021-07-22T21:54:26.915",
"status": "ACCEPTED",
"statusDesc": "Accepted successfully"
“PVNo”:”ILMS0000BP00001”
}

"BPPaylist": {
"PayeeCode": "20210722205348",
"EndToEnd": "E20210722205348",
}
}
},
"digitalSignature":
"ixIt2a7tcFiolZzPvxl0GqRz7B8GcqDlppyj0vKvKXyMXnQM4ofXTjqWRnELob5Tge5nOi4xkiAb0PXdV2wjg
QxMgDwFifNXfxqV1XkHySXi8JDuMrWuxd+gKvbLuZXpwYgyJxXUSrdCPJS4gIUQE2rzMwAgSmks4awd
5mNQQ/94x+W0JuHGkr677O4zwLSi2XzFtAsVKj/3Crc/
fdkG9NaEOQ1gVuIMeW+ciCNXNL4Z86QVOlUnKMmp602nY2ZUTqDE6uWklsb6L/eov3HJlIYNo/
+VaqZ/2LT9djqNA3iH4IhQfWW8uz7PIF9OsKhFY0oVedIyqNIxCVapMY3RKg=="}

4.4.2 Failure Response

{
"message": {
"messageHeader": {
"sender": "FBUS",
"receiver": "ILMS",
"msgId": "FBUS20210722215426884",
"messageType": "ACK",

10 | P a g e
 "paymentType": "PV"
},
"messageSummary": {
"orgMsgId": "20210722205348",
"createdAt": "2021-07-22T21:54:26.915",
"status": "Rejected",
"statusDesc": "Invalid Signature"

}
},
"digitalSignature":
"ixIt2a7tcFiolZzPvxl0GqRz7B8GcqDlppyj0vKvKXyMXnQM4ofXTjqWRnELob5Tge5nOi4xkiAb0PXdV2wjg
QxMgDwFifNXfxqV1XkHySXi8JDuMrWuxd+gKvbLuZXpwYgyJxXUSrdCPJS4gIUQE2rzMwAgSmks4awd
5mNQQ/94x+W0JuHGkr677O4zwLSi2XzFtAsVKj/3Crc/
fdkG9NaEOQ1gVuIMeW+ciCNXNL4Z86QVOlUnKMmp602nY2ZUTqDE6uWklsb6L/eov3HJlIYNo/
+VaqZ/2LT9djqNA3iH4IhQfWW8uz7PIF9OsKhFY0oVedIyqNIxCVapMY3RKg=="}

4.5 Unapplied Message Notification

Payments which could not be credited to customer’s accounts will be returned to MUSE as
unapplied transaction. Upon receiving of unapplied transactions MUSE will notify Paying
Institution system using the following messages:

4.4.2 Payment Voucher Unapplied Notification

{
"message": {
"messageHeader": {
"sender": "FBUS",
"receiver": "ILMS",
"msgId": "FBUS20210722215426884",
"messageType": "Unapplied",
"paymentType": "PV"
},
"messageSummary": {
"orgMsgId": "20210722205348",
“PVNo”:”ILMS0000v2200001”
"createdAt": "2021-07-22T21:54:26.915",
"status": "Unapplied",
"statusDesc": "Account Name Mismatch"

}
},
"digitalSignature":
"ixIt2a7tcFiolZzPvxl0GqRz7B8GcqDlppyj0vKvKXyMXnQM4ofXTjqWRnELob5Tge5nOi4xkiAb0PXdV2wjg
QxMgDwFifNXfxqV1XkHySXi8JDuMrWuxd+gKvbLuZXpwYgyJxXUSrdCPJS4gIUQE2rzMwAgSmks4awd
5mNQQ/94x+W0JuHGkr677O4zwLSi2XzFtAsVKj/3Crc/

11 | P a g e
 fdkG9NaEOQ1gVuIMeW+ciCNXNL4Z86QVOlUnKMmp602nY2ZUTqDE6uWklsb6L/eov3HJlIYNo/
+VaqZ/2LT9djqNA3iH4IhQfWW8uz7PIF9OsKhFY0oVedIyqNIxCVapMY3RKg=="}

4.4.3 Bulky Payment Unapplied Notification

{
"message": {
"messageHeader": {
"sender": "FBUS",
"receiver": "ILMS",
"msgId": "FBUS20210722215426884",
"messageType": "Unapplied",
"paymentType": "PV"
},
"messageSummary": {
"orgMsgId": "20210722205348",
“BatchNo”:”ILMS0000B2200001”
“EndtoEndID”:”ILMS0000E22200001”
"createdAt": "2021-07-22T21:54:26.915",
"status": "Unapplied",
"statusDesc": "Account Name Mismatch"

}
},
"digitalSignature":
"ixIt2a7tcFiolZzPvxl0GqRz7B8GcqDlppyj0vKvKXyMXnQM4ofXTjqWRnELob5Tge5nOi4xkiAb0PXdV2wjg
QxMgDwFifNXfxqV1XkHySXi8JDuMrWuxd+gKvbLuZXpwYgyJxXUSrdCPJS4gIUQE2rzMwAgSmks4awd
5mNQQ/94x+W0JuHGkr677O4zwLSi2XzFtAsVKj/3Crc/
fdkG9NaEOQ1gVuIMeW+ciCNXNL4Z86QVOlUnKMmp602nY2ZUTqDE6uWklsb6L/eov3HJlIYNo/
+VaqZ/2LT9djqNA3iH4IhQfWW8uz7PIF9OsKhFY0oVedIyqNIxCVapMY3RKg=="}

5 Digital Signature Security

5.1 Overview
Digital signature will be used for messages exchange between the Payment originating systems and MUSE. In case
of failure of to verify the signature messages will be rejected with the reason “Digital Signature Failed”.

5.2 Digital Signature

The security architecture used by the MUSE is based on Public Key Infrastructure (PKI) technology in which
two keys (Public and Private) are used. The keys are generated using digital certificates downloaded by the
Central CA Server. PKI digital certificates are used for access control and digital signature.

12 | P a g e
5.3 Format of Digital Signature
The files and message will be digitally signed using the PKCS12 standard. This provides authentication, message
integrity and non-repudiation of origin. The standard describes a general syntax for data that may have cryptography
applied to it, such as digital signatures and digital envelopes.
MUSE and payment originating system will exchange public keys for signature verifications. Original message will
be separated with signature by using pipe ‘|’. Final message after digitally signed will be as shown below

13 | P a g e