Getting Started

This guide walks you from zero to your first successful API call in under ten minutes.

1. Create an account and log in

1. Go to your organisation's Salami instance at https://yourtenant.salami.dgl.co.ke.
2. Sign up with your business email. You will receive a verification link.
3. Verify your email and log in.
4. Complete your profile -- fill in your business name, phone number, and any required KYC details.

If your organisation already has a Salami tenant, ask your administrator to invite you. You will receive an email with a link to set your password.

2. Create your first app

Salami organises credentials around apps. Each app represents one integration channel -- a specific M-Pesa shortcode, an SMS sender ID, or a set of KRA API credentials. You can have many apps per module.

Payment app

1. Navigate to Payments > Payment Apps > Add New.
2. Select the provider (e.g. M-Pesa C2B, M-Pesa B2C, Airtel Money, Equity EazzyPay).
3. Enter the provider credentials:
   • M-Pesa: Consumer Key, Consumer Secret, Shortcode, Passkey.
   • Airtel Money: Client ID, Client Secret, Subscriber ID.
   • Equity: API Key, Merchant Code.
4. Set your callback URL -- the endpoint on your server where payment notifications will be sent.
5. Toggle Test Mode if you want to use the Safaricom sandbox or Salami simulator.
6. Click Save.

SMS app

1. Navigate to SMS > SMS Apps > Add New.
2. Choose a provider (Africa's Talking, Twilio, etc.) or select Android Gateway to use your own phone.
3. Enter the provider API key and sender ID.
4. Click Save.

KRA app

1. Navigate to KRA > Apps > Add New.
2. Select the app type:
   • Portal -- for developer.go.ke APIs (checkers, PRN generation, returns, etc.).
   • eTIMS OSCU -- for electronic invoicing.
3. Enter the required credentials:
   • Portal: Client ID, Client Secret from the KRA developer portal, plus the taxpayer KRA PIN.
   • eTIMS OSCU: TIN, BHFID (branch ID), Device Serial Number.
4. Choose the environment: Sandbox or Production.
5. Click Save.
6. For eTIMS, click Initialize Device to register with KRA and download code tables.

3. Generate an API token

API tokens authenticate your server-to-server requests. Every request to the Salami API must include a valid token.

From the dashboard

1. Go to Account > API Tokens > Add New Token.
2. Give it a descriptive name (e.g. production-server, staging-erp).
3. Select the scopes (permissions) this token needs. Start narrow and expand later. See the full list in Authentication.
4. Optionally set an expiry date.
5. Click Save.
6. Copy the token immediately. It is shown only once. Store it in your environment variables or a secrets manager.

From the API

curl -X POST https://yourtenant.salami.dgl.co.ke/account/api_tokens \
  -H "Content-Type: application/json" \
  -H "Cookie: <your-session-cookie>" \
  -d '{
    "name": "my-server-token",
    "abilities": "payments:read,payments:write",
    "expires_at": "2027-01-01"
  }'

Response:

{
  "success": true,
  "token": "1|a8Bk3xY9z...plainTextToken",
  "msg": "API token created successfully"
}

4. Make your first API call

Once you have a token, include it in the Authorization header of every request:

Authorization: Bearer 1|a8Bk3xY9z...plainTextToken

Example -- List your payment apps

curl -s https://yourtenant.salami.dgl.co.ke/api/pay/apps \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Accept: application/json" | jq .

{
  "status_code": 200,
  "status_name": "HTTP_OK",
  "message": "OK",
  "data": [
    {
      "id": 1,
      "name": "My M-Pesa Till",
      "type": "MpesaKeC2B",
      "is_live": true,
      "created_at": "2025-06-01T08:30:00Z"
    }
  ]
}

Example -- Send an SMS

curl -s -X POST https://yourtenant.salami.dgl.co.ke/api/sms/apps/1/send \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "+254712345678",
    "message": "Hello from Salami Gateway!"
  }' | jq .

{
  "success": true,
  "data": {
    "sms_id": 5432,
    "status": "sent",
    "recipient": "+254712345678"
  },
  "message": "SMS sent successfully"
}

Example -- Validate a KRA PIN

curl -s -X POST https://yourtenant.salami.dgl.co.ke/api/kra/checkers/pin \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -H "X-KRA-App-Id: 1" \
  -d '{
    "KRAPIN": "P051234567A"
  }' | jq .

{
  "success": true,
  "data": {
    "TaxpayerName": "ACME LIMITED",
    "KRAPIN": "P051234567A",
    "TaxPayerType": "Non-Individual",
    "Status": "Active"
  }
}

Example -- Submit an eTIMS sale

curl -s -X POST https://yourtenant.salami.dgl.co.ke/api/kra/etims/sales/submit \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "date": "2026-03-29",
    "trader_invoice_number": "INV-001",
    "receipt_type_code": "S",
    "customer_tin": "P051234567A",
    "customer_name": "Acme Limited",
    "sales_tax_summary": {
      "taxable_amount_a": 0,
      "taxable_amount_b": 8620.69,
      "taxable_amount_c": 0,
      "taxable_amount_d": 0,
      "tax_rate_a": 0,
      "tax_rate_b": 16,
      "tax_rate_c": 0,
      "tax_rate_d": 0,
      "tax_amount_a": 0,
      "tax_amount_b": 1379.31,
      "tax_amount_c": 0,
      "tax_amount_d": 0
    }
  }' | jq .

{
  "success": true,
  "message": "Sale submitted to eTims successfully",
  "data": {
    "id": 789,
    "trader_invoice_number": "INV-001",
    "cu_invoice_number": "CU20260329-001",
    "status": "submitted"
  }
}

5. Test in sandbox mode

Every module supports a sandbox or test mode so you can develop without touching real money or filing real returns.

Payments

• Toggle Test Mode on your payment app in the dashboard.
• M-Pesa sandbox credentials are available from the Safaricom developer portal. Alternatively, use the built-in Salami Simulator (POST /api/pay/{app}/simulateTransaction) to fabricate callbacks locally.

SMS

• Create an SMS app using a test provider or the Android Gateway pointed at a test device.
• Messages sent in test mode appear in the outbox but are not delivered to the carrier.

KRA

• Set your KRA app environment to Sandbox.
• Portal sandbox uses the KRA UAT environment at https://apisandbox.kra.go.ke.
• eTIMS sandbox connects to KRA's VSCU test environment. Initialize your device in sandbox before submitting test invoices.

Sandbox vs. production checklist

6. Go-live checklist

Before switching to production, verify every item below.

• Account verified -- email confirmed, business profile complete.
• App credentials -- live provider credentials entered and tested (use the Test App button).
• API token -- production token created with minimum necessary scopes.
• HTTPS everywhere -- all callback URLs and API requests use HTTPS.
• Error handling -- your code checks the success field and handles 4xx/5xx responses gracefully.
• Idempotency -- payment requests use unique references to avoid double charges.
• Callback endpoint -- returns 200 quickly; does heavy processing asynchronously.
• Logging -- all API requests and responses are logged on your side for debugging.
• Rate limits -- your integration stays within 200 requests per minute per token.
• eTIMS device initialized -- (if applicable) device registered and code tables synced in production.
• KRA PIN registered -- (if applicable) your production KRA app uses the correct taxpayer PIN.

Next steps

• Authentication -- deep dive into tokens, scopes, and per-request app selection.
• Error Codes -- understand every error your integration might encounter.
• Payments API -- full endpoint reference for payments.
• SMS API -- full endpoint reference for messaging.
• eTIMS API -- full endpoint reference for electronic invoicing.

Need help? Email support@dgl.co.ke or check the FAQs.