# Developer Platform Welcome to your team’s developer platform

Help and Support

Download App Merchant Login

{% columns %} {% column %} ### Get started in 5 minutes Setting up your first API call should be the easiest part of getting started. With clear endpoints, copy-paste-ready examples, and quick authentication, you’ll be up and running in minutes—not hours. No guesswork, no complexity—just your first successful call, fast. Get started API reference {% endcolumn %} {% column %} {% code title="bash" overflow="wrap" %} ```bash curl -X GET \ https://api.sarafa.ss/v1/wallets \ -H 'api-key: your_secret_key_here' ``` {% endcode %} {% endcolumn %} {% endcolumns %}

Simplifying Money, Unlock Global Opportunities

# Developer Guide Learn more about documenting APIs in GitBook. The Sarafa API (Application Programming Interface) provides a powerful and versatile way for your business to programmatically interact with the Sarafa platform. By leveraging the API, you can seamlessly integrate Sarafa’s financial functionalities into your existing applications, workflows, and systems, unlocking new levels of automation and efficiency. To begin utilizing the Sarafa API, you will need to generate an API key. ## Authentication To interact with the Sarafa API, you will utilize API keys for authentication. * **Format:** Secret keys follow the UUID version 4 (Universally Unique Identifier) format. ``` xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx ``` Example: `a1b2c3d4-e5f6-4789-9012-34567890abcd` ## Base URL All API requests to Sarafa should be directed to the following base URL for the production environment: * * ## API Usage You will need to include your API key in the header of every API request for authentication. The key should be passed in a header with the name `api-key`. ```bash curl -X GET \ https://api.sarafa.live/v2/wallets \ -H 'api-key: your_secret_key_here' ``` All responses from the Sarafa API will be formatted in JSON.Example JSON Response (Success - HTTP 200 OK): ``` { "status": "success", "data": { "account_number": "9020260000001", "wallets": [ { "balance": 1009.19, "currency": "USD", "meta": null }, ... ] } } ``` Error Handling The Sarafa API uses standard HTTP status codes to indicate the outcome of your requests.200 OK: This status code indicates that your request was successful and you are properly authenticated with a valid API key. The response body will contain the requested data in JSON format (as shown in the example above).401 Unauthorized: This status code indicates that your API key is invalid, missing, or has expired. Ensure you are including a valid API key in the api-key header of your request.When integrating with the Sarafa API, it’s crucial to handle these HTTP status codes appropriately to ensure your application functions correctly and provides informative feedback. Always store your secret keys securely and only use public keys in client-side code. # Setup Authentication, Base URLs and Usage ## Authentication To interact with the Sarafa API, you will utilize API keys for authentication. * **Format:** Secret keys follow the UUID version 4 (Universally Unique Identifier) format. ``` xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx ``` Example: `a1b2c3d4-e5f6-4789-9012-34567890abcd` ## Base URL All API requests to Sarafa should be directed to the following base URLs for the production environment: * **** * **** ## API Usage You will need to include your API key in the header of every API request for authentication. The key should be passed in a header with the name `api-key`. ```bash curl -X GET \ https://api.sarafa.live/v2/wallets \ -H 'api-key: your_secret_key_here' ``` All responses from the Sarafa API will be formatted in JSON.Example JSON Response (Success - HTTP 200 OK): ```json { "status": "success", "data": { "account_number": "9020260000001", "wallets": [ { "balance": 1009.19, "currency": "USD", "meta": null } ] }, } ``` Error Handling The Sarafa API uses standard HTTP status codes to indicate the outcome of your requests. 200 OK: This status code indicates that your request was successful and you are properly authenticated with a valid API key. The response body will contain the requested data in JSON format (as shown in the example above). 401 Unauthorized: This status code indicates that your API key is invalid, missing, or has expired. Ensure you are including a valid API key in the api-key header of your request.When integrating with the Sarafa API, it’s crucial to handle these HTTP status codes appropriately to ensure your application functions correctly and provides informative feedback. Always store your secret keys securely. # API and Transaction Limits To ensure fair usage and maintain the stability of the Sarafa API, we implement rate limiting on the number of requests you can make within a specific time window. Currently, the API is limited to **2500 query requests every 10 minutes** per API key.If you exceed this limit, the API will return a **429 Too Many Requests** error response. **Example JSON Response (Too Many Requests - HTTP 429):** ```json { "status": "error", "message": "Too many requests. Please wait and try again later." } ``` When you receive a 429 error, your application should implement a retry mechanism with an appropriate backoff strategy (e.g., waiting for a few seconds before attempting the request again). Avoid aggressive retries to prevent further overloading the API. You can monitor your API usage to stay within the defined limits. ### [​](https://readme.sarafa.ss/api-reference/limits#transactions-limits)Transactions Limits The following table outlines the default transaction limits for SSP, UGX, and KES stablecoin backed wallets within the Sarafa platform. Please note that these limits may vary based on your business’s KYC/KYB verification level. You can view your specific limits within your account dashboard. | Currency | Charge | Transfers | | -------- | --------------- | --------------- | | SSP | 100-2,000,000 | 100-2,000,000 | | UGX | 5,000-3,950,000 | 5,000-3,950,000 | | KES | 100-150,000 | 100-150,000 | | USD | 1 - 10,000 | 1 - 10,000 | ### [​](https://readme.sarafa.ss/api-reference/limits#important-notes:)Important Notes: These limits are per transaction are as per our integration partners and cannot be increased, changed or modified # Error Codes When interacting with the Sarafa API, you may encounter various error codes indicating issues with your requests. Understanding these codes will help you troubleshoot and resolve integration problems more effectively. Here’s a list of common error codes and their descriptions: * **400 Bad Request:** The server could not understand the request due to invalid syntax or missing parameters. Review the request body and headers to ensure they conform to the API specification. * **401 Unauthorized:** The API key provided in the `api-key` header is invalid, missing, or has expired. Ensure you are using a valid and active API key. * **403 Forbidden:** Your API key is valid, but it does not have the necessary permissions to access the requested resource or perform the requested action. Check the scope and permissions associated with your API key. * **404 Not Found:** The requested resource could not be found on the server. Verify the API endpoint URL and ensure it is correct. * **405 Method Not Allowed:** The HTTP method used in the request (e.g., GET, POST, PUT, DELETE) is not supported for the requested resource. Refer to the API documentation for the allowed methods for each endpoint. * **409 Conflict:** The request could not be completed due to a conflict with the current state of the resource (e.g., attempting to create a resource that already exists). * **422 Unprocessable Entity:** The server understood the request, but it was unable to process the contained instructions. This is often due to validation errors in the request body (e.g., incorrect data types, invalid values). The response body will usually contain details about the validation failures. **Example JSON Response (Unprocessable Entity - HTTP 422):** ```json { "status": "error", "message": "Invalid Data", } ``` * **429 Too Many Requests:** You have exceeded the API rate limit. Your application should implement a retry mechanism with an appropriate backoff strategy. * **500 Internal Server Error:** The server encountered an unexpected error and was unable to fulfill the request. This is usually a server-side issue. If you encounter this error consistently, please contact our support team with the request details and the error response. * **503 Service Unavailable:** The server is temporarily unavailable due to maintenance or overload. Your application should retry the request after a short delay. When integrating with the Sarafa API, ensure your application is designed to handle these error codes gracefully and provide informative feedback or retry mechanisms as appropriate. # Webhooks Sarafa can send real-time event notifications to your application via webhooks. This allows you to stay informed about important events, such as successful payments or transaction status updates, without the need for continuous polling of the API. You can include a `callback_url` in your API requests to specify the endpoint where these webhook events should be sent.When a relevant event occurs, Sarafa will send an HTTP POST request to the `callback_url` you provided. The body of this request will contain a JSON object detailing the event.To receive webhooks, you need to: 1. Have a publicly accessible URL (`callback_url`) that can accept HTTP POST requests. 2. Configure this `callback_url` in the relevant API request when initiating an action that might trigger a webhook event (e.g., creating a payment link). 3. Implement logic on your server at the `callback_url` to receive and process the incoming webhook data. **Example of Including `callback_url` in an API Request (e.g., /charge ):** ```json { "phone": "255712345678", "amount": "25.00", "currency": "SSP", "callback_url": "https://your-application.com/webhooks/sarafa" } ``` **Sample Webhook Payload (JSON):**The structure of the webhook payload will vary depending on the event that triggered it. Here’s an example of a webhook payload for a successful payment on a paylink: ```json { "data": { "tx_id": "tx_abcdef1234567890", } } ``` [
](https://readme.sarafa.ss/api-reference/errors) # Sarafa API ## Get All Wallets > Retrieve the main account number and a list of all wallets with their balances. ```json {"openapi":"3.0.3","info":{"title":"Sarafa API","version":"2.0.0"},"servers":[{"url":"https://api.sarafa.live/v2","description":"Production Server","variables":{}}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","name":"api-key","in":"header"}},"schemas":{"BaseResponse":{"type":"object","properties":{"status":{"description":"Response status (e.g., 'success', 'error', 'ok')","type":"string"}}},"WalletObject":{"type":"object","properties":{"currency":{"$ref":"#/components/schemas/CurrencyEnum"},"balance":{"format":"double","type":"number"}}},"CurrencyEnum":{"description":"Supported currencies.","enum":["USD","UGX","KES","SSP"],"type":"string"},"ErrorResponse":{"type":"object","properties":{"status":{"type":"string"},"message":{"description":"Description of the error.","type":"string"}}}},"responses":{"UnauthorizedError":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Unauthorized / Invalid API Key"}}},"paths":{"/wallets":{"get":{"responses":{"200":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/BaseResponse"},{"type":"object","properties":{"data":{"type":"object","properties":{"account_number":{"type":"string"},"wallets":{"type":"array","items":{"$ref":"#/components/schemas/WalletObject"}}}}}}]}}},"description":"Successful retrieval of wallets"},"401":{"$ref":"#/components/responses/UnauthorizedError"}},"operationId":"getWallets","summary":"Get All Wallets","description":"Retrieve the main account number and a list of all wallets with their balances."}}}} ``` ## Get Specific Wallet > Retrieve balance and details for a specific currency wallet. ```json {"openapi":"3.0.3","info":{"title":"Sarafa API","version":"2.0.0"},"servers":[{"url":"https://api.sarafa.live/v2","description":"Production Server","variables":{}}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","name":"api-key","in":"header"}},"schemas":{"CurrencyEnum":{"description":"Supported currencies.","enum":["USD","UGX","KES","SSP"],"type":"string"},"BaseResponse":{"type":"object","properties":{"status":{"description":"Response status (e.g., 'success', 'error', 'ok')","type":"string"}}},"WalletObject":{"type":"object","properties":{"currency":{"$ref":"#/components/schemas/CurrencyEnum"},"balance":{"format":"double","type":"number"}}},"ErrorResponse":{"type":"object","properties":{"status":{"type":"string"},"message":{"description":"Description of the error.","type":"string"}}}},"responses":{"NotFoundError":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Resource Not Found"}}},"paths":{"/wallet/{currency}":{"get":{"parameters":[{"name":"currency","description":"The currency code of the wallet to retrieve.","schema":{"$ref":"#/components/schemas/CurrencyEnum"},"in":"path","required":true}],"responses":{"200":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/BaseResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/WalletObject"}}}]}}},"description":"Successful retrieval of wallet"},"404":{"$ref":"#/components/responses/NotFoundError"}},"operationId":"getWalletByCurrency","summary":"Get Specific Wallet","description":"Retrieve balance and details for a specific currency wallet."}}}} ``` ## View Transaction > Retrieve detailed information about a specific transaction. ```json {"openapi":"3.0.3","info":{"title":"Sarafa API","version":"2.0.0"},"servers":[{"url":"https://api.sarafa.live/v2","description":"Production Server","variables":{}}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","name":"api-key","in":"header"}},"schemas":{"BaseResponse":{"type":"object","properties":{"status":{"description":"Response status (e.g., 'success', 'error', 'ok')","type":"string"}}},"TransactionDetail":{"type":"object","properties":{"tx_id":{"type":"string"},"amount":{"format":"double","type":"number"},"currency":{"$ref":"#/components/schemas/CurrencyEnum"},"initiated_at":{"format":"date-time","type":"string"},"completed_at":{"format":"date-time","type":"string"},"status":{"type":"string"},"total_amount":{"format":"double","type":"number"},"total_fees":{"format":"double","type":"number"},"transaction_type":{"type":"string"},"product":{"type":"string"},"description":{"type":"string"},"customer_meta":{"description":"Arbitrary customer metadata","type":"object","additionalProperties":true}}},"CurrencyEnum":{"description":"Supported currencies.","enum":["USD","UGX","KES","SSP"],"type":"string"},"ErrorResponse":{"type":"object","properties":{"status":{"type":"string"},"message":{"description":"Description of the error.","type":"string"}}}},"responses":{"NotFoundError":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Resource Not Found"}}},"paths":{"/transaction/{tx_id}":{"get":{"parameters":[{"name":"tx_id","description":"The unique transaction ID.","schema":{"type":"string"},"in":"path","required":true}],"responses":{"200":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/BaseResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/TransactionDetail"}}}]}}},"description":"Transaction details found"},"404":{"$ref":"#/components/responses/NotFoundError"}},"operationId":"getTransaction","summary":"View Transaction","description":"Retrieve detailed information about a specific transaction."}}}} ``` ## Get Exchange Rates > Retrieve the current list of exchange rate pairs. ```json {"openapi":"3.0.3","info":{"title":"Sarafa API","version":"2.0.0"},"servers":[{"url":"https://api.sarafa.live/v2","description":"Production Server","variables":{}}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","name":"api-key","in":"header"}},"schemas":{"BaseResponse":{"type":"object","properties":{"status":{"description":"Response status (e.g., 'success', 'error', 'ok')","type":"string"}}}}},"paths":{"/rates":{"get":{"responses":{"200":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/BaseResponse"},{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"pair":{"type":"string"},"rate":{"format":"float","type":"number"}}}}}}]}}},"description":"List of rates"}},"operationId":"getRates","summary":"Get Exchange Rates","description":"Retrieve the current list of exchange rate pairs."}}}} ``` ## Initiate Charge > Initiate a charge request. ```json {"openapi":"3.0.3","info":{"title":"Sarafa API","version":"2.0.0"},"servers":[{"url":"https://api.sarafa.live/v2","description":"Production Server","variables":{}}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","name":"api-key","in":"header"}},"schemas":{"CurrencyEnum":{"description":"Supported currencies.","enum":["USD","UGX","KES","SSP"],"type":"string"},"BaseResponse":{"type":"object","properties":{"status":{"description":"Response status (e.g., 'success', 'error', 'ok')","type":"string"}}},"ErrorResponse":{"type":"object","properties":{"status":{"type":"string"},"message":{"description":"Description of the error.","type":"string"}}}},"responses":{"BadRequestError":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Bad Request / Validation Error"}}},"paths":{"/charge":{"post":{"requestBody":{"content":{"application/json":{"schema":{"required":["amount","currency","account_number","reference","callback_url"],"type":"object","properties":{"amount":{"format":"double","type":"number"},"currency":{"$ref":"#/components/schemas/CurrencyEnum"},"account_number":{"description":"Payer's account number","type":"string"},"reference":{"description":"External reference ID","type":"string"},"callback_url":{"format":"uri","type":"string"}}}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/BaseResponse"},{"type":"object","properties":{"data":{"type":"object","properties":{"tx_id":{"type":"string"},"callback_url":{"type":"string"},"checkout_url":{"type":"string"}}}}}]}}},"description":"Charge initiated successfully"},"400":{"$ref":"#/components/responses/BadRequestError"}},"operationId":"createCharge","summary":"Initiate Charge","description":"Initiate a charge request."}}}} ``` ## Initiate Transfer > Transfer funds to a mobile money or Sarafa account. ```json {"openapi":"3.0.3","info":{"title":"Sarafa API","version":"2.0.0"},"servers":[{"url":"https://api.sarafa.live/v2","description":"Production Server","variables":{}}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","name":"api-key","in":"header"}},"schemas":{"CurrencyEnum":{"description":"Supported currencies.","enum":["USD","UGX","KES","SSP"],"type":"string"},"BaseResponse":{"type":"object","properties":{"status":{"description":"Response status (e.g., 'success', 'error', 'ok')","type":"string"}}},"ErrorResponse":{"type":"object","properties":{"status":{"type":"string"},"message":{"description":"Description of the error.","type":"string"}}}},"responses":{"BadRequestError":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Bad Request / Validation Error"}}},"paths":{"/transfer":{"post":{"requestBody":{"content":{"application/json":{"schema":{"required":["amount","currency","destination","account_number","reference","callback_url"],"type":"object","properties":{"amount":{"format":"double","type":"number"},"currency":{"$ref":"#/components/schemas/CurrencyEnum"},"destination":{"description":"Type of destination for the transfer.","enum":["mobile","sarafa"],"type":"string"},"account_number":{"description":"Recipient account number","type":"string"},"reference":{"type":"string"},"callback_url":{"format":"uri","type":"string"}}}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/BaseResponse"},{"type":"object","properties":{"data":{"type":"object","properties":{"tx_id":{"type":"string"}}}}}]}}},"description":"Transfer initiated successfully"},"400":{"$ref":"#/components/responses/BadRequestError"}},"operationId":"createTransfer","summary":"Initiate Transfer","description":"Transfer funds to a mobile money or Sarafa account."}}}} ``` ## Health Check > Check the operational status of the API. ```json {"openapi":"3.0.3","info":{"title":"Sarafa API","version":"2.0.0"},"servers":[{"url":"https://api.sarafa.live/v2","description":"Production Server","variables":{}}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","name":"api-key","in":"header"}},"schemas":{"BaseResponse":{"type":"object","properties":{"status":{"description":"Response status (e.g., 'success', 'error', 'ok')","type":"string"}}}}},"paths":{"/":{"get":{"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BaseResponse"}}},"description":"API is healthy"}},"operationId":"getHealth","summary":"Health Check","description":"Check the operational status of the API.","tags":[]}}}} ```