To Mobile Wallets

Test URL

Live URL

The Real Time Gross Settlement (RTGS) web-service enables an application to send money intra-country to other bank accounts.

❗️ CDD - KYC & CFT

In line with various banking regulations your send money transaction will be subjected to various verifications and you may be required to provide additional information.

🚧 Transaction Time

RTGS is available on weekdays between 9am and 3pm. If you send after these hours, your transaction will be queued and sent at the next available transaction window.

RTGS Remittance Request Fields

200 Success Response Schema

Example Request

transfer.reference+transfer.date+source.accountNumber+destination.accountNumber+transfer.amount

Request Parameters

curl -X POST \
	-d '{
            "source": {
                "countryCode": "KE",
                "currency":"KES",
                "name": "John Doe",
                "accountNumber": "0020100014605"
            },
            "destination": {
                "type": "bank",
                "countryCode": "KE",
                "name": "David Mwangi",
                "bankCode": "61",
                "accountNumber": "1100194977404"
            },
            "transfer": {
                "type": "RTGS",
                "amount": "200",
                "currencyCode": "KES",
                "reference": "16110014834489833",
                "date": "2023-10-13",
                "description": "Some remarks here",
                "purposeOfPaymentCode": "OTHR"
                }
        }'  \
	-H 'Authorization: Bearer {access_token}'  \
	-H 'Content-Type: application/json'  \
	-H 'signature: e967CLKebZyLfa73/YYltjW5M4cHoyWeHi/5VDKJ64gOwKBvzHJRqJJrBBc34v2m4jyKkDMBtfRJeFlxbNisMAeBtkw0TRcD2LThFK27EOqLM3m8rQYa+7CJ2FhPhK+iOa4RUY+vTfkRX5JXuqOW7a3GHds8qyPaPe19cKUY33eAJL3upXnGnA3/PEhzjhb0pqk2zCI7aRzvjjVUGwUdT6LO73NVhDSWvGpLEsP0dH/stC5BoTPNNt9nY8yvGUPV7fmaPSIFn68W4L04WgePQdYkmD1UPApGcrl+L2ALY3lPaRfI6/N+0Y3NIWQyLgix+69k7V4EGolqejWdion+9A=='  \
	-L 'https://uat.finserve.africa/v3-apis/transaction-api/v3.0/remittance'

Example Response

{
    "status": true,
    "code": 0,
    "message": "success",
    "reference": "16110014834489833",
    "data": {
        "transactionId": "16110014834489833",
        "status": "SUCCESS"
    }
}

🚀 RTGS Payment Purpose

📥 GET /v3.0/rtgs/paymentPurpose

📋 Overview

This endpoint retrieves the purposes for RTGS (Real-Time Gross Settlement) payments.

🛠️ Request

🌐 Live url

🔗 Test url

🔍 Response Fields Description

Sample Response

{
    "status": true,
    "code": 200,
    "message": "Success",
    "data": [
        {
            "code": "CUR/DEP",
            "value": "CASH DEPOSITS"
        },
        {
            "code": "CUR/WIT",
            "value": "CASH WITHDRAWALS"
        },
        {
            "code": "CSDK",
            "value": "Central Security Depository Payments"
        },
        {
            "code": "OTHR",
            "value": "Other"
        }
    ]
}

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

Transaction Status Errors

📖 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:

transfer.reference+transfer.date+source.accountNumber+destination.accountNumber+transfer.amount

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: transfer.reference+transfer.date+source.accountNumber+destination.accountNumber+transfer.amount
   • 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: transfer.reference+transfer.date+source.accountNumber+destination.accountNumber+transfer.amount
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