> For the complete documentation index, see [llms.txt](https://docs.sarafa.live/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.sarafa.live/api-reference/reference/sarafa-api.md).

# 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":[]}}}}
```