Receive Payments - Bill Validation

Test URL

Live URL

This web service enables your application perform a bill validation. This is typically before a payment is made for example before paying a utility bill you would like the payment application to validate it actually exists and its details are correct

200 Success Response Schema

Example Request

billerCode+amount+amountCurrency

Request Fields

curl -X POST \
	-d '{
            "billerCode": "320320",
            "customerRefNumber": "28055948",
            "amount": "1000.00",
            "amountCurrency": "KES"
        }'  \
	-H 'Authorization: Bearer 5fDAgGPdA98EF53ul4YAvR3XWC39'  \
	-H 'Content-Type: application/json'  \
	-L 'https://uat.finserve.africa/v3-apis/transaction-api/v3.0/bills/validation'

Example Response

{
    "status": true,
    "code": 0,
    "message": "success",
    "data": {
        "amount": "1000.0",
        "customerRefNumber": "101704",
        "name": "John Doe",
        "billStatus": "true",
        "message": "SUCCESS",
        "createdOn": "Fri Jun 24 11:04:14 EAT 2022",
        "amountCurrency": "KES",
        "status": true
    }
}

Error Responses

400 Bad Request

Missing or invalid parameters in the request body.

{
  "status": false,
  "code": 400,
  "message": "Invalid request parameters",
  "error_code": "INVALID_REQUEST"
}

401 Unauthorized

Invalid or expired access token.

{
  "status": false,
  "code": 401,
  "message": "Invalid or expired access token",
  "error_code": "UNAUTHORIZED"
}

403 Forbidden

Valid credentials but invalid signature or insufficient permissions.

{
  "status": false,
  "code": 403,
  "message": "Invalid signature or insufficient permissions",
  "error_code": "FORBIDDEN"
}

404 Not Found

Account not found or invalid account number.

{
  "status": false,
  "code": 404,
  "message": "Source or destination account not found",
  "error_code": "ACCOUNT_NOT_FOUND"
}

📖 Step-by-Step Guide

Step 1: 🔑 Set Up Security Keys

Generate your private and public key pair and share your public key with Finserve. See the Security & Signatures Documentation (opens in a new tab) for detailed instructions.

Step 2: 🎫 Authenticate

Obtain an access token using the authentication endpoint. See the Authentication API documentation (opens in a new tab) for details.

Step 3: 📋 Prepare Transaction Details

Gather all required information.

Step 4: ✍️ Generate Signature

Create the signature string by concatenating in this exact order:

billerCode+amount+amountCurrency

Sign this string using your private key, then Base64 encode the result.

Step 5: 📝 Set Up Headers

Include the following headers in your request:

• Content-Type: application/json
• Authorization: Bearer [your_access_token]
• Signature: [your_base64_encoded_signature]

Step 6: 🔧 Construct Request Body

Create a JSON object with all required fields following the structure shown in the example request.

Step 7: 🚀 Send POST Request

Make a POST request to the internal bank transfer endpoint with your headers and body.

🌍 Supported Countries & Currencies

Best Practices

1. ** Security**

   • Store your private key securely and never expose it in client-side code or version control
   • Always use HTTPS for API requests
   • Store access tokens securely
   • Regenerate signatures for each request

2. ** Signature Generation**

   • Ensure exact string concatenation order: billerCode+amount+amountCurrency
   • Do not include spaces, separators, or special characters in the concatenated string
   • Always Base64 encode the signature before including it in headers
   • Verify the values in the signature match exactly with the request body values

3. ** Transaction Reference**

   • Use unique reference numbers for each transaction
   • Implement a reference generation system to avoid duplicates
   • Store reference numbers for reconciliation and audit purposes
   • Never reuse reference numbers, even for failed transactions

4. Amount Formatting

   • Always use decimal format with two decimal places (e.g., "500.00")
   • Pass amounts as strings, not numbers
   • Ensure the amount is positive and within allowed limits
   • Verify amount matches exactly in signature and request body

5. Error Handling

   • Implement retry logic with exponential backoff for transient errors
   • Log transaction attempts and responses for audit purposes
   • Handle signature validation errors by regenerating the signature

6. Testing

   • Always test with the UAT endpoint before using the live endpoint
   • Use test account numbers provided in the documentation
   • Verify signature generation with sample data first
   • Test error scenarios to ensure proper handling

7. Data Validation

   • Validate all account numbers match the expected format
   • Verify country codes are valid and supported
   • Ensure transfer dates are in the correct format (YYYY-MM-DD)
   • Validate currency codes match the destination country

Troubleshooting

Invalid Signature Error (403)

If you receive a 403 error with "Invalid signature":

1. Verify the concatenation order: billerCode + amount + amountCurrency
2. Ensure no spaces or separators are included in the concatenated string
3. Check that the signature is Base64 encoded
4. Verify your public key is correctly registered with us
5. Ensure the values in the signature match exactly with the request body values

Common Signature Mistakes

• Using wrong concatenation order
• Adding spaces or separators between values
• Not Base64 encoding the final signature
• Values in signature don't match request body values

Support

For questions or issues with this API:

• Email: support@finserve.africa