Transactions
Transactions are the core entities in the Sentinal system, representing financial exchanges between parties.
They capture essential details about the monetary amount, the involved client, the country of operation, and the applied fees. Transactions also maintain a status indicating their current state, such as "APPROVED" or "DECLINED".
Verify transactions
This endpoint allows the PSP to verify a transaction before allowing it to be processed. The system will respond with the split in VAT, processing fees, and the amount that can be settled to the client. Based on the client's overall standing, the transaction will be approved or declined. If a transaction is declined, the PSP should not process the transaction further. The endpoint can be used to either create a new transaction or update an existing one.
POST /v1/transaction/verifyTransaction
Headers
x-api-key*
string
Request Body
ref*
string
External reference
totalAmount*
number
currency*
string
countryCode*
string
paymentMethods*
object
{"card": 130.50, "vouchers": 10, "discounts": 5, "cash": 5}
transactionFee*
number
PSP's transaction fee for the payment
transactionID
string
If Submit Basket was used by client
mcc
string
Merchant Categorisation Code of the transaction
{
"success": true,
"message": "Transaction verified successfully.",
"content": {
"transactionId": "WBzywJCj9D8Kago2dDFj",
"vatAmount": 11.2875,
"processingFee": 0.4214,
"merchantAmount": 138.7911,
"transactionFee": 100,
"transactionVAT": 7.5,
"status": "APPROVED",
"ref": "12345"
}
}Verify Transaction Status
Retrieve the status and details of a specific transaction. This endpoint ensures that only authorised clients can view the transaction details.
GET https://api.sentinal.network/v1/transaction/verifyTransactionStatus
Retrieve the status and details of a specific transaction. This endpoint ensures that only authorised clients can view the transaction details.
Query Parameters
transactionId*
string
Headers
x-api-key
string
{
"success": true,
"message": "Transaction status retrieved successfully.",
"content": {
"transactionId": "WBzywJCj9D8Kago2dDFj",
"totalAmount": 150.5,
"createdAt": {
"_seconds": 1695816492,
"_nanoseconds": 684000000
},
"ref": "12345",
"merchantAmount": 138.7911,
"paymentMethods": {
"discounts": 5,
"vouchers": 10,
"cash": 5,
"card": 130.5
},
"currency": "NGN",
"vatAmount": 11.2875,
"processingFee": 0.4214,
"transactionFee": 100,
"transactionVAT": 7.5,
"status": "APPROVED",
"countries": [
{
"name": "Nigeria",
"countryCode": "NG"
}
]
}
}Decline transactions
This endpoint enables Payment Service Providers (PSPs) to decline a transaction that has previously been verified or flagged for review. The endpoint requires a transaction reference to be specified, and it will update the transaction's status to 'DECLINED' if it is found in the database. This is crucial for handling cases where a transaction must be stopped due to issues like fraud detection, customer disputes, or compliance violations. The response will confirm the successful update of the transaction status. This function ensures that PSPs have the necessary controls to manage transaction flows effectively, enhancing security and adherence to regulatory standards.
POST https://api.sentinal.network/v1/transaction/declineTransaction
Headers
x-api-key*
string
Request Body
ref*
string
External reference
json
{
"success": true,
"message": "Transaction status updated to DECLINED.",
"content": {
"transactionId": "exampleTransactionId123",
"ref": "exampleRef456"
}
}
Record Chargeback
This endpoint allows Payment Service Providers (PSPs) to record a chargeback for a previously verified transaction. The endpoint requires a transaction reference to be specified and ensures that only the PSP that initially recorded the transaction can file the chargeback. This functionality is essential for handling cases such as disputed transactions, fraud, or customer complaints. The endpoint verifies that a chargeback has not already been recorded for the transaction and creates a new chargeback record in the database if the conditions are met.
The amounts received in the response (such as vatAmount, processingFee, merchantAmount, transactionFee, and transactionVAT) should be subtracted from what must be settled to the parties in the split payments from the next transactions to reverse the original transaction amounts. This ensures accurate settlement and reversal of funds related to the chargeback.
The response confirms the successful recording of the chargeback and provides the relevant details.
POST https://api.sentinal.network/v1/transaction/chargeBack
Headers
x-api-key*
string
Request Body
ref*
string
External reference
json
{
"success": true,
"message": "Chargeback recorded successfully.",
"content": {
"chargebackId": "66660d3d391654c0fdacf77f",
"transactionId": "6665de9a2dc52b33b25c2579",
"vatAmount": 4.31,
"processingFee": 0.28,
"merchantAmount": 95.41,
"transactionFee": 100,
"transactionVAT": 6.98,
"status": "APPROVED",
"ref": "Test1121212"
}
}Last updated