feat(onekhusa): add push and inline checkout support

.changeset/quiet-push-payments.md

@@ -0,0 +1,6 @@
+---
+"@chiahq/sdk": minor
+"@chiahq/mcp": minor
+---
+
+Add OneKhusa direct mobile money push payments, hosted checkout sessions for inline modal or redirect use, webhook types, and matching MCP tools.

docs/docs/mcp/claude-desktop.md

@@ -29,6 +29,8 @@ Add the following to your Claude Desktop config file:
         "ONEKHUSA_API_KEY": "your-onekhusa-api-key",
         "ONEKHUSA_API_SECRET": "your-onekhusa-api-secret",
         "ONEKHUSA_ORGANISATION_ID": "your-organisation-id",
+        "ONEKHUSA_MERCHANT_ACCOUNT_NUMBER": "35253486",
+        "ONEKHUSA_DEFAULT_CAPTURED_BY": "payments@example.com",
         "ENVIRONMENT": "DEVELOPMENT"
       }
     }
@@ -45,6 +47,8 @@ Add the following to your Claude Desktop config file:
 | `ONEKHUSA_API_KEY` | OneKhusa | Your OneKhusa API key |
 | `ONEKHUSA_API_SECRET` | OneKhusa | Your OneKhusa API secret |
 | `ONEKHUSA_ORGANISATION_ID` | OneKhusa | Your OneKhusa organisation ID |
+| `ONEKHUSA_MERCHANT_ACCOUNT_NUMBER` | OneKhusa | Merchant account used for OneKhusa requests |
+| `ONEKHUSA_DEFAULT_CAPTURED_BY` | OneKhusa | Default operator email for collection requests |
 | `ENVIRONMENT` | All | `DEVELOPMENT` or `PRODUCTION` |
 
 :::tip
@@ -99,6 +103,8 @@ You only need to configure the providers you plan to use. Leave out the environm
         "ONEKHUSA_API_KEY": "your-api-key",
         "ONEKHUSA_API_SECRET": "your-api-secret",
         "ONEKHUSA_ORGANISATION_ID": "your-org-id",
+        "ONEKHUSA_MERCHANT_ACCOUNT_NUMBER": "35253486",
+        "ONEKHUSA_DEFAULT_CAPTURED_BY": "payments@example.com",
         "ENVIRONMENT": "DEVELOPMENT"
       }
     }

docs/docs/mcp/overview.md

@@ -10,7 +10,7 @@ import Version from '@site/src/components/Version';
 
 <Version pkg="mcp" />
 
-Model Context Protocol server enabling AI assistants like Claude to handle payment operations through natural language. **48 comprehensive tools**: 4 provider-agnostic unified tools plus dedicated tools for PayChangu, PawaPay, and OneKhusa.
+Model Context Protocol server enabling AI assistants like Claude to handle payment operations through natural language. **50 comprehensive tools**: 4 provider-agnostic unified tools plus dedicated tools for PayChangu, PawaPay, and OneKhusa.
 
 ## What is MCP?
 
@@ -24,7 +24,7 @@ Instead of writing code, you can simply ask:
 
 ## Features
 
-- **48 Tools** - Comprehensive coverage of all payment operations
+- **50 Tools** - Comprehensive coverage of all payment operations
 - **Unified by Default** - Provider-agnostic tools that route for you, so most tasks don't need a specific provider named
 - **Natural Language** - Interact with payments using plain English
 - **Multiple Providers** - PayChangu, PawaPay, and OneKhusa support
@@ -37,7 +37,7 @@ Instead of writing code, you can simply ask:
 | Unified | 4 | Provider-agnostic collections and payouts, routed by country and currency |
 | PayChangu | 12 | Payments, transfers, mobile money, bank payouts |
 | PawaPay | 14 | Deposits, payouts, refunds, wallets, config |
-| OneKhusa | 18 | Collections, single/batch disbursements |
+| OneKhusa | 20 | Direct push, hosted checkout, collections, single/batch disbursements |
 
 ## Quick Example
 

docs/docs/mcp/tools/onekhusa.md

@@ -4,19 +4,35 @@ title: OneKhusa Tools
 description: OneKhusa MCP tools reference
 ---
 
-# OneKhusa Tools (18)
+# OneKhusa Tools (20)
 
 MCP tools for OneKhusa payment operations.
 
-## Collections (3 tools)
+## Collections (5 tools)
 
 ### Initiate Request-to-Pay
 
-Request payment from a customer.
+Reserve a timed account number for the customer to pay into.
 
 **Example prompts:**
-- *"Request a payment of 5000 MWK from 265991234567 using OneKhusa"*
-- *"Initiate a OneKhusa collection for 10000 MWK"*
+- *"Reserve a OneKhusa timed account number for 5000 MWK"*
+- *"Initiate a OneKhusa request-to-pay for order ORDER12345"*
+
+### Initiate Direct Push
+
+Start a USSD prompt on the customer's mobile money wallet. The final outcome arrives through webhooks.
+
+**Example prompts:**
+- *"Send a OneKhusa payment prompt for 5000 MWK to 265991234567"*
+- *"Start a direct OneKhusa push using connector 550044"*
+
+### Initiate Standard Checkout
+
+Create a hosted checkout session and return a URL that can be opened in a modal or redirect.
+
+**Example prompts:**
+- *"Create a OneKhusa checkout for 150 MWK and return to my success and failure pages"*
+- *"Start a OneKhusa inline checkout for order ORDER12345"*
 
 ### Get Collection Transactions
 
@@ -37,107 +53,107 @@ Get details for a specific collection.
 
 ### Add Single Disbursement
 
-Create a payout to one recipient.
+Create a payout to one beneficiary using their OneKhusa connector and account number.
 
 **Example prompts:**
-- *"Create a OneKhusa disbursement of 10000 MWK to John Doe at 265991234567"*
+- *"Create a OneKhusa disbursement of 10000 to John Doe at 265991234567 using connector 550044"*
 - *"Send a single payout via OneKhusa"*
 
 ### Approve Disbursement
 
-Approve a pending disbursement.
+Approve a pending disbursement using its transaction reference number.
 
 **Example prompts:**
-- *"Approve OneKhusa disbursement DIS_12345"*
+- *"Approve OneKhusa transaction reference PAYOUT123"*
 
 ### Review Disbursement
 
-Mark a disbursement as reviewed.
+Mark a disbursement as reviewed using its transaction reference number.
 
 **Example prompts:**
-- *"Review disbursement DIS_12345"*
+- *"Review OneKhusa transaction reference PAYOUT123"*
 
 ### Reject Disbursement
 
-Reject a disbursement.
+Reject a disbursement using its transaction reference number.
 
 **Example prompts:**
-- *"Reject disbursement DIS_12345 because of incorrect details"*
+- *"Reject OneKhusa transaction reference PAYOUT123 because of incorrect details"*
 
 ### Get Disbursement Details
 
-Check disbursement status.
+Check disbursement details using its transaction reference number.
 
 **Example prompts:**
-- *"Get status of disbursement DIS_12345"*
+- *"Get details for OneKhusa transaction reference PAYOUT123"*
 
 ## Batch Disbursements (9 tools)
 
 ### Add Batch Disbursement
 
-Create a batch with multiple recipients.
+Create a batch with beneficiary entries. Each entry includes a connector, beneficiary account, amount, description, and source reference.
 
 **Example prompts:**
-- *"Create a batch disbursement for January salaries with 3 recipients totaling 150000 MWK"*
+- *"Create a OneKhusa batch for January salaries with 3 beneficiary entries totaling 150000"*
 - *"Start a OneKhusa batch payout"*
 
 ### Approve Batch
 
-Approve a batch for processing.
+Approve a batch using its numeric batch number.
 
 **Example prompts:**
-- *"Approve batch BATCH_12345"*
+- *"Approve OneKhusa batch number 12345"*
 
 ### Review Batch
 
-Mark a batch as reviewed.
+Mark a batch as reviewed using its numeric batch number.
 
 **Example prompts:**
-- *"Review batch BATCH_12345"*
+- *"Review OneKhusa batch number 12345"*
 
 ### Reject Batch
 
-Reject a batch.
+Reject a batch, optionally identifying its header ID.
 
 **Example prompts:**
-- *"Reject batch BATCH_12345 - budget not approved"*
+- *"Reject OneKhusa batch header 12345 because the budget was not approved"*
 
 ### Cancel Batch
 
-Cancel a batch.
+Cancel a pending batch using its numeric batch number.
 
 **Example prompts:**
-- *"Cancel batch BATCH_12345"*
+- *"Cancel OneKhusa batch number 12345"*
 
 ### Transfer Batch Funds
 
-Process payment for an approved batch.
+Transfer funds for an approved batch using its numeric batch number.
 
 **Example prompts:**
-- *"Transfer funds for batch BATCH_12345"*
-- *"Process batch BATCH_12345"*
+- *"Transfer funds for OneKhusa batch number 12345"*
+- *"Process OneKhusa batch number 12345"*
 
 ### Get All Batches
 
-List your batches.
+List batches for a transaction date and page.
 
 **Example prompts:**
 - *"Show my OneKhusa batches"*
-- *"Get all pending batches"*
+- *"List OneKhusa disbursement batches for 2026-10-31"*
 
 ### Get Batch Details
 
-Get details for a specific batch.
+Get details for a specific batch number.
 
 **Example prompts:**
-- *"Get details for batch BATCH_12345"*
+- *"Get details for OneKhusa batch number 12345"*
 
 ### Get Batch Transactions
 
-List transactions within a batch.
+List transactions within a batch using its numeric batch number.
 
 **Example prompts:**
-- *"Show transactions in batch BATCH_12345"*
+- *"Show transactions in OneKhusa batch number 12345"*
 
 ## Config (1 tool)
 

docs/docs/mcp/troubleshooting.md

@@ -97,7 +97,8 @@ The provider isn't configured. Add the required environment variables:
     "PAWAPAY_JWT": "...",
     "ONEKHUSA_API_KEY": "...",
     "ONEKHUSA_API_SECRET": "...",
-    "ONEKHUSA_ORGANISATION_ID": "..."
+    "ONEKHUSA_ORGANISATION_ID": "...",
+    "ONEKHUSA_MERCHANT_ACCOUNT_NUMBER": "35253486"
   }
 }
 ```

docs/docs/sdk/configuration.md

@@ -35,6 +35,7 @@ const sdk = ChiaSDK.initialize({
     apiKey: "your-api-key",
     apiSecret: "your-api-secret",
     organisationId: "your-organisation-id",
+    merchantAccountNumber: 35253486,
     environment: ENVIRONMENTS.DEVELOPMENT
   }
 });
@@ -62,6 +63,7 @@ PAWAPAY_ENVIRONMENT=DEVELOPMENT
 ONEKHUSA_API_KEY=your-onekhusa-api-key
 ONEKHUSA_API_SECRET=your-onekhusa-api-secret
 ONEKHUSA_ORGANISATION_ID=your-organisation-id
+ONEKHUSA_MERCHANT_ACCOUNT_NUMBER=35253486
 ONEKHUSA_ENVIRONMENT=DEVELOPMENT
 
 # Chia platform - enables automatic provider routing and sdk.platform.*
@@ -110,6 +112,7 @@ const sdk = ChiaSDK.initialize({
     apiKey: "your-api-key",
     apiSecret: "your-api-secret",
     organisationId: "your-organisation-id",
+    merchantAccountNumber: 35253486,
     environment: ENVIRONMENTS.DEVELOPMENT,
     sandboxUrl: "https://custom-sandbox.onekhusa.com/v1",
     productionUrl: "https://custom-prod.onekhusa.com/v1"
@@ -121,8 +124,8 @@ const sdk = ChiaSDK.initialize({
 Both `sandboxUrl` and `productionUrl` are optional. If not provided, the SDK uses the default provider URLs. The URL used depends on the `environment` setting.
 :::
 
-:::note OneKhusa OAuth
-For OneKhusa, the SDK automatically appends `/oauth/token` to custom URLs for authentication endpoints.
+:::note OneKhusa token scope
+OneKhusa access tokens are scoped to a merchant account. Configure the merchant account number used for the token and collection requests.
 :::
 
 ## Selective Provider Configuration
@@ -149,6 +152,7 @@ const multiProvider = ChiaSDK.initialize({
     apiKey: process.env.ONEKHUSA_API_KEY || "",
     apiSecret: process.env.ONEKHUSA_API_SECRET || "",
     organisationId: process.env.ONEKHUSA_ORGANISATION_ID || "",
+    merchantAccountNumber: Number(process.env.ONEKHUSA_MERCHANT_ACCOUNT_NUMBER),
     environment: ENVIRONMENTS.PRODUCTION
   }
 });