@afriex/sdk 4.1.0 → 5.1.0

package/README.md

@@ -72,6 +72,7 @@ const session = await afriex.checkout.createSession({
   currency: "USD",
   merchantReference: "order-123",
   redirectUrl: "https://example.com/checkout/complete",
+  channels: ["VIRTUAL_BANK_ACCOUNT", "MOBILE_MONEY", "CARD"],
   customer: {
     name: "John Doe",
     email: "john@example.com",
@@ -79,7 +80,7 @@ const session = await afriex.checkout.createSession({
     countryCode: "US",
   },
 });
-// session.checkoutUrl
+// session.checkoutUrl, session.channels
 
 // Webhook verification (requires webhookPublicKey)
 const isValid = afriex.webhooks.verify(payload, signature);
@@ -92,9 +93,12 @@ const isValid = afriex.webhooks.verify(payload, signature);
 | `afriex.customers`      | Customer CRUD, KYC updates, and document verification       |
 | `afriex.transactions`   | Create, authorize, list, and track transactions             |
 | `afriex.paymentMethods` | Bank, mobile money, crypto wallets, virtual & pool accounts |
+| `afriex.paymentBatches` | Pay many recipients in one call                             |
 | `afriex.balance`        | Organization wallet balances and sandbox top-ups            |
 | `afriex.rates`          | Exchange rates and conversions                              |
 | `afriex.checkout`       | Hosted checkout sessions (card, virtual account, momo)      |
+| `afriex.media`          | Upload invoices, payment proofs and documents               |
+| `afriex.smeRegistration` | Register the business for dedicated KES virtual accounts   |
 | `afriex.webhooks`       | Webhook signature verification and sandbox test triggers    |
 
 Every service is always available on the client. `afriex.webhooks.verify()` returns `false`
@@ -114,10 +118,21 @@ interface AfriexSDKConfig {
     maxRetries: number;
     retryDelay: number;
     retryableStatusCodes: number[]; // Default: [408, 429, 500, 502, 503, 504]
+    retryableMethods?: HttpMethod[]; // Default: every method except POST and PATCH
   };
+  apiVersion?: string; // Default: '2026-05-18', sent as x-api-version
+  signRequest?: RequestSigner; // Optional - returns the x-api-signature value
+  userAgent?: string; // Default: 'Afriex-TypeScript-SDK/<version of @afriex/sdk>'
 }
 ```
 
+`SDK_VERSION` holds the version of `@afriex/sdk` that is installed.
+
+Retries are off by default. When they are on, `POST` and `PATCH` requests are
+still sent once unless `retryableMethods` lists them. See
+[`@afriex/core`](https://www.npmjs.com/package/@afriex/core) for retries and
+request signing.
+
 `staging` points at `https://sandbox.api.afriex.com/api/v1`, `production` at
 `https://api.afriex.com/api/v1`.
 
@@ -153,9 +168,12 @@ For smaller bundle sizes, install packages individually:
 | `@afriex/customers`       | Customer management and KYC                            |
 | `@afriex/transactions`    | Transaction handling                                   |
 | `@afriex/payment-methods` | Payment methods, institutions, virtual & pool accounts |
+| `@afriex/payment-batches` | Bulk payouts to a saved list of recipients             |
 | `@afriex/balance`         | Balance queries and sandbox top-ups                    |
 | `@afriex/rates`           | Exchange rates and conversions                         |
 | `@afriex/checkout`        | Hosted checkout sessions                               |
+| `@afriex/media`           | File uploads                                           |
+| `@afriex/sme-registration` | SME registration for KES virtual accounts             |
 | `@afriex/webhooks`        | Webhook verification and test triggers                 |
 
 Each service package depends only on `@afriex/core`, so you can mix and match.

package/dist/index.d.ts

@@ -6,6 +6,9 @@ import { BalanceService } from "@afriex/balance";
 import { RateService } from "@afriex/rates";
 import { CheckoutService } from "@afriex/checkout";
 import { WebhookService } from "@afriex/webhooks";
+import { MediaService } from "@afriex/media";
+import { PaymentBatchService } from "@afriex/payment-batches";
+import { SmeRegistrationService } from "@afriex/sme-registration";
 export interface AfriexSDKConfig extends AfriexConfig {
     webhookPublicKey?: string;
 }
@@ -13,14 +16,18 @@ export declare class AfriexSDK extends AfriexClient {
     readonly customers: CustomerService;
     readonly transactions: TransactionService;
     readonly paymentMethods: PaymentMethodService;
+    readonly paymentBatches: PaymentBatchService;
     readonly balance: BalanceService;
     readonly rates: RateService;
     readonly checkout: CheckoutService;
+    readonly media: MediaService;
+    readonly smeRegistration: SmeRegistrationService;
     readonly webhooks: WebhookService;
     readonly webhookVerifier?: WebhookService;
     constructor(config: AfriexSDKConfig);
 }
 export { AfriexSDK as Afriex };
+export { SDK_VERSION } from "./version.js";
 export * from "@afriex/core";
 export { CustomerService } from "@afriex/customers";
 export { TransactionService } from "@afriex/transactions";
@@ -29,12 +36,19 @@ export { BalanceService } from "@afriex/balance";
 export { RateService } from "@afriex/rates";
 export { CheckoutService } from "@afriex/checkout";
 export { WebhookVerifier, WebhookService } from "@afriex/webhooks";
-export type { Customer, CustomerKyc, CustomerMeta, KycDocumentType, CreateCustomerRequest, UpdateCustomerRequest, UpdateCustomerKycRequest, VerifyCustomerRequest, ListCustomersParams, CustomerListResponse, } from "@afriex/customers";
-export type { Transaction, CreateTransactionRequest, AuthorizeTransactionRequest, ListTransactionsParams, TransactionListResponse, TransactionListType, TransactionChannel, TransactionType, TransactionStatus, TransactionMeta, TransactionMetaResponse, TransactionFailureCode, TransactionFailureReason, } from "@afriex/transactions";
-export type { PaymentMethod, PaymentMethodInstitution, PaymentMethodRecipient, PaymentMethodTransaction, CreatePaymentMethodRequest, ListPaymentMethodsParams, PaymentMethodListResponse, PaymentChannel, CreatablePaymentChannel, PaymentMethodStatus, CardBrand, CardExpiration, Institution, InstitutionListResponse, InstitutionListChannel, InstitutionCode, InstitutionCodesParams, InstitutionCodesResponse, ResolveAccountParams, ResolvedAccount, ResolveAccountResponse, GetInstitutionsParams, CryptoWallet, CryptoWalletData, CryptoWalletResponse, GetCryptoWalletParams, ListVirtualAccountsParams, CreateVirtualAccountParams, ListPoolAccountsParams, VirtualAccountListResponse, PoolAccountResponse, } from "@afriex/payment-methods";
-export type { BalanceResponse, GetBalanceParams } from "@afriex/balance";
+export { MediaService } from "@afriex/media";
+export { PaymentBatchService } from "@afriex/payment-batches";
+export { SmeRegistrationService } from "@afriex/sme-registration";
+export type { Customer, CustomerKyc, CustomerMeta, KycDocumentType, UpdatableKycDocumentType, ReadOnlyKycDocumentType, CreateCustomerRequest, UpdateCustomerRequest, UpdateCustomerKycRequest, VerifyCustomerRequest, ListCustomersParams, CustomerListResponse, } from "@afriex/customers";
+export type { Transaction, CreateTransactionRequest, CreateWithdrawTransaction, CreateDepositTransaction, CreateSwapTransaction, TransactionAmount, TransactionAmounts, SwapAmount, AuthorizeTransactionRequest, SimulateTransactionRequest, SimulateTransactionOutcome, SettlementAdvice, SubmitPoolAccountProofRequest, PoolAccountProofSender, ListTransactionsParams, TransactionListResponse, TransactionListType, TransactionListStatus, TransactionSettlement, TransactionChannel, TransactionType, TransactionMeta, TransactionMetaResponse, TransactionFailureCode, TransactionFailureReason, } from "@afriex/transactions";
+export type { PaymentMethod, PaymentMethodBankAddress, PaymentMethodInstitution, PaymentMethodRecipient, PaymentMethodTransaction, CreatePaymentMethodRequest, CreateInstitutionPaymentMethodRequest, CreateAliasPaymentMethodRequest, CreateVirtualBankAccountPaymentMethodRequest, AliasPaymentChannel, InstitutionPaymentChannel, ListPaymentMethodsParams, PaymentMethodListResponse, PaymentMethodListChannel, PaymentMethodListStatus, PaymentMethodListCapability, VirtualAccountLabel, PaymentChannel, CreatablePaymentChannel, PaymentMethodStatus, CardBrand, CardExpiration, Institution, InstitutionListResponse, InstitutionListChannel, InstitutionCode, InstitutionCodesParams, InstitutionCodesResponse, ResolveAccountParams, ResolvedAccount, ResolveAccountResponse, GetInstitutionsParams, CryptoWallet, CryptoWalletData, CryptoWalletResponse, GetCryptoWalletParams, ListVirtualAccountsParams, CreateVirtualAccountParams, ListPoolAccountsParams, VirtualAccountListResponse, PoolAccountResponse, SimulateTransferRequest, SimulateTransferResult, } from "@afriex/payment-methods";
+export type { BalanceResponse, GetBalanceParams, TopUpParams, TopUpResponse, TopUpTransaction, TopUpTransactionType, TopUpTransactionStatus, } from "@afriex/balance";
 export type { RatesResponse, GetRatesParams } from "@afriex/rates";
-export type { CheckoutSession, CreateCheckoutSessionRequest, CheckoutCustomer, CheckoutChannel, } from "@afriex/checkout";
-export type { WebhookPayload, CustomerWebhookPayload, CustomerEventType, CustomerWebhookData, PaymentMethodWebhookPayload, PaymentMethodEventType, PaymentMethodWebhookData, TransactionWebhookPayload, TransactionEventType, TransactionWebhookData, TransactionWebhookStatus, CheckoutSessionWebhookPayload, CheckoutSessionEventType, CheckoutSessionWebhookData, TriggerWebhookRequest, TriggerWebhookResult, TriggerWebhookResponse, WebhookEventType, } from "@afriex/webhooks";
+export type { CheckoutSession, CreateCheckoutSessionRequest, CreateCheckoutSessionResponse, CheckoutCustomer, CheckoutChannel, } from "@afriex/checkout";
+export type { MediaUploadType, CreateUploadUrlRequest, UploadUrl, UploadableFile, UploadFileRequest, UploadedFile, } from "@afriex/media";
+export type { PaymentBatch, PaymentBatchRequest, PaymentBatchSource, PaymentBatchFundingMethod, PaymentBatchListItem, PaymentBatchListParams, PaymentBatchListResponse, PaymentBatchInstitution, PaymentBatchAmount, PaymentBatchRecipientRequest, UpdatePaymentBatchRecipientRequest, SavedPaymentBatchRecipient, PaymentBatchRecipient, PaymentBatchRecipientListResponse, PaymentBatchOutcomes, WithdrawPaymentBatchParams, PaymentBatchSession, PaymentBatchSessionResult, PaymentBatchSessionListResponse, } from "@afriex/payment-batches";
+export type { SmeRegistration, SmeRegistrationRequest, SmeRegistrationStep, SmeRegistrationStatus, SmeRegistrationStatusResult, SmeReviewStatus, SmeBusinessType, InitiateSmeRegistrationData, ConfirmSmeRegistrationOtpData, SubmitSmeRegistrationData, } from "@afriex/sme-registration";
+export type { WebhookPayload, CustomerWebhookPayload, CustomerEventType, CustomerWebhookData, PaymentMethodWebhookPayload, PaymentMethodEventType, PaymentMethodWebhookData, TransactionWebhookPayload, TransactionEventType, TransactionWebhookData, TransactionWebhookMeta, TransactionWebhookFailureReason, TransactionWebhookStatus, CheckoutSessionWebhookPayload, CheckoutSessionEventType, CheckoutSessionWebhookData, CheckoutSessionWebhookCustomer, PoolDepositRequestWebhookPayload, PoolDepositRequestEventType, PoolDepositRejectedWebhookData, TriggerWebhookRequest, TriggerWebhookResult, TriggerWebhookResponse, WebhookEventType, TriggerableWebhookEventType, WebhookEnvelope, } from "@afriex/webhooks";
 export { WEBHOOK_SIGNATURE_HEADER } from "@afriex/webhooks";
+export { TransactionStatus, DEFAULT_TRANSACTION_TYPE, } from "@afriex/transactions";
 //# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -1,4 +1,5 @@
-import { AfriexClient } from "@afriex/core";
+import { AfriexClient, DEFAULT_USER_AGENT, } from "@afriex/core";
+import { SDK_VERSION } from "./version.js";
 import { CustomerService } from "@afriex/customers";
 import { TransactionService } from "@afriex/transactions";
 import { PaymentMethodService } from "@afriex/payment-methods";
@@ -6,16 +7,25 @@ import { BalanceService } from "@afriex/balance";
 import { RateService } from "@afriex/rates";
 import { CheckoutService } from "@afriex/checkout";
 import { WebhookService } from "@afriex/webhooks";
+import { MediaService } from "@afriex/media";
+import { PaymentBatchService } from "@afriex/payment-batches";
+import { SmeRegistrationService } from "@afriex/sme-registration";
 export class AfriexSDK extends AfriexClient {
     constructor(config) {
-        super(config);
+        super({
+            ...config,
+            userAgent: config.userAgent || `${DEFAULT_USER_AGENT}/${SDK_VERSION}`,
+        });
         const httpClient = this.getHttpClient();
         this.customers = new CustomerService(httpClient);
         this.transactions = new TransactionService(httpClient);
         this.paymentMethods = new PaymentMethodService(httpClient);
+        this.paymentBatches = new PaymentBatchService(httpClient);
         this.balance = new BalanceService(httpClient);
         this.rates = new RateService(httpClient);
         this.checkout = new CheckoutService(httpClient);
+        this.media = new MediaService(httpClient);
+        this.smeRegistration = new SmeRegistrationService(httpClient);
         this.webhooks = new WebhookService(httpClient, config.webhookPublicKey);
         if (config.webhookPublicKey) {
             this.webhookVerifier = this.webhooks;
@@ -24,6 +34,7 @@ export class AfriexSDK extends AfriexClient {
 }
 // Short alias
 export { AfriexSDK as Afriex };
+export { SDK_VERSION } from "./version.js";
 // Re-export core types
 export * from "@afriex/core";
 // Re-export service classes explicitly to avoid conflicts
@@ -34,5 +45,10 @@ export { BalanceService } from "@afriex/balance";
 export { RateService } from "@afriex/rates";
 export { CheckoutService } from "@afriex/checkout";
 export { WebhookVerifier, WebhookService } from "@afriex/webhooks";
+export { MediaService } from "@afriex/media";
+export { PaymentBatchService } from "@afriex/payment-batches";
+export { SmeRegistrationService } from "@afriex/sme-registration";
 export { WEBHOOK_SIGNATURE_HEADER } from "@afriex/webhooks";
+// `TransactionStatus` is a value as well as a type, so it is exported as both.
+export { TransactionStatus, DEFAULT_TRANSACTION_TYPE, } from "@afriex/transactions";
 //# sourceMappingURL=index.js.map

package/dist/version.d.ts

@@ -0,0 +1,8 @@
+/**
+ * The version of `@afriex/sdk`, sent in the `User-Agent` header.
+ *
+ * Kept equal to the version in package.json by `scripts/sync-sdk-version.mjs`,
+ * which runs as part of `pnpm run version`. Do not edit it by hand.
+ */
+export declare const SDK_VERSION = "5.1.0";
+//# sourceMappingURL=version.d.ts.map

package/dist/version.js

@@ -0,0 +1,8 @@
+/**
+ * The version of `@afriex/sdk`, sent in the `User-Agent` header.
+ *
+ * Kept equal to the version in package.json by `scripts/sync-sdk-version.mjs`,
+ * which runs as part of `pnpm run version`. Do not edit it by hand.
+ */
+export const SDK_VERSION = "5.1.0";
+//# sourceMappingURL=version.js.map

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@afriex/sdk",
-  "version": "4.1.0",
-  "description": "Official TypeScript SDK for the Afriex Business API",
+  "version": "5.1.0",
+  "description": "Official TypeScript SDK for the Afriex Business API: cross-border payouts, collections, virtual accounts, exchange rates and webhooks",
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -20,14 +20,17 @@
     }
   },
   "dependencies": {
-    "@afriex/core": "2.1.0",
-    "@afriex/customers": "3.1.0",
-    "@afriex/transactions": "2.1.0",
-    "@afriex/payment-methods": "4.1.0",
-    "@afriex/balance": "2.0.0",
-    "@afriex/rates": "2.0.1",
-    "@afriex/checkout": "3.0.1",
-    "@afriex/webhooks": "2.0.0"
+    "@afriex/customers": "4.0.0",
+    "@afriex/transactions": "3.0.0",
+    "@afriex/payment-methods": "5.0.0",
+    "@afriex/balance": "2.1.0",
+    "@afriex/core": "2.2.0",
+    "@afriex/rates": "2.0.2",
+    "@afriex/checkout": "3.1.0",
+    "@afriex/payment-batches": "1.0.0",
+    "@afriex/webhooks": "3.1.0",
+    "@afriex/media": "1.0.0",
+    "@afriex/sme-registration": "1.0.0"
   },
   "devDependencies": {
     "@tanstack/intent": "^0.3.6",
@@ -48,12 +51,25 @@
   },
   "keywords": [
     "afriex",
-    "sdk",
-    "api",
-    "money-transfer",
     "payments",
     "fintech",
+    "africa",
+    "cross-border-payments",
     "typescript",
+    "afriex-sdk",
+    "sdk",
+    "api",
+    "payments-api",
+    "api-client",
+    "money-transfer",
+    "remittance",
+    "payouts",
+    "mobile-money",
+    "bank-transfer",
+    "nigeria",
+    "kenya",
+    "ghana",
+    "nodejs",
     "tanstack-intent"
   ],
   "license": "MIT",

package/skills/afriex-go-live/SKILL.md

@@ -90,8 +90,24 @@ export const afriex = new AfriexSDK({
 
 Fail condition: no `retryConfig` — `DEFAULT_CONFIG` sets `maxRetries: 0`, so a
 single 503 fails the request outright.
-Fix: supply `retryConfig`, and make sure every retried write carries a stable
-`meta.idempotencyKey`.
+Fix: supply `retryConfig`.
+
+### Check: writes are not retried blindly
+
+Expected: `retryConfig.retryableMethods` is absent, or lists neither `POST`
+nor `PATCH`.
+
+With the default methods, the SDK retries reads and sends every `POST` and
+`PATCH` once. A write that fails with a 5xx or a timeout may still have been
+applied, so the application reads the state back (for a transaction,
+`transactions.list({ reference })`) before it sends the write again, and
+reuses the same `meta.idempotencyKey` when it does.
+
+Fail condition: `retryableMethods` includes `POST` on a client that calls
+`paymentBatches.withdraw` — a repeat starts a second run and pays every
+recipient again.
+Fix: remove `POST` from `retryableMethods` and retry writes in application
+code, where the state can be checked first.
 
 ### Check: request logging does not leak request bodies
 
@@ -188,12 +204,50 @@ export async function seedTestWallet(): Promise<void> {
 }
 ```
 
-Fail condition: `topUpSandbox` or `triggerTestWebhook` reachable on a
-production code path — both answer `403 FORBIDDEN` there.
+Fail condition: `balance.topUpSandbox`, `webhooks.triggerTestWebhook`,
+`transactions.simulate` or `paymentMethods.simulateTransfer` reachable on a
+production code path — all four answer `403 FORBIDDEN` there.
 Fix: guard them behind an environment check or keep them in test-only modules.
 
+### Check: no sandbox test value reaches production
+
+Expected:
+
+```ts
+const SANDBOX_OUTCOME_SUFFIXES = ["0001", "0002", "0003", "0004", "0005"];
+
+export function assertRealAccount(accountNumber: string): void {
+  if (process.env.NODE_ENV !== "production") {
+    return;
+  }
+  if (SANDBOX_OUTCOME_SUFFIXES.some((suffix) => accountNumber.endsWith(suffix))) {
+    console.warn("account number matches a sandbox test value", accountNumber);
+  }
+}
+```
+
+In the sandbox, an account number, phone number or card number ending in
+`0001` to `0005` chooses the outcome of a transaction, the OTP is always
+`123456`, and `SIMULATE_INSTANT` in `meta.reference` completes a transaction
+early. None of this applies in production, where those are ordinary values.
+
+Fail condition: a fixture account, the OTP `123456` or a `SIMULATE_INSTANT`
+reference hard-coded on a path that runs in production.
+Fix: keep test values in fixtures that only the test environment loads.
+
 ## Webhook Checks
 
+### Check: the firewall admits Afriex's webhook addresses
+
+Expected: inbound traffic to the webhook endpoint is allowed from
+`34.197.33.100` in production and `34.234.189.210` in the sandbox.
+
+Fail condition: a firewall or allowlist in front of the endpoint that does not
+include the address for the environment — deliveries are dropped before they
+reach the handler, and nothing is logged on the application side.
+Fix: add the address to the allowlist. The address is not a substitute for
+verifying the signature.
+
 ### Check: the endpoint verifies signatures against the raw body
 
 Expected:
@@ -319,10 +373,13 @@ Source: packages/core/src/errors/ApiError.ts
 - [ ] API key read from a secret store; no key in source or client bundles
 - [ ] Separate sandbox and production keys; `environment` set explicitly
 - [ ] `retryConfig` configured — retries are off by default
+- [ ] `retryableMethods` does not include `POST` or `PATCH`
+- [ ] Afriex's webhook IP address is allowed through the firewall
 - [ ] `logLevel` is `LogLevel.ERROR` in production
 - [ ] Every `transactions.create` carries a persisted, reused `meta.idempotencyKey`
 - [ ] Order state settles on `TRANSACTION.UPDATED`, not on `create()` resolving
-- [ ] `topUpSandbox` and `triggerTestWebhook` are unreachable in production
+- [ ] `topUpSandbox`, `triggerTestWebhook`, `simulate` and `simulateTransfer` are unreachable in production
+- [ ] No sandbox test account, OTP or `SIMULATE_INSTANT` reference on a production path
 - [ ] Webhook route uses a raw body parser and `verifyAndParse`
 - [ ] `AFRIEX_WEBHOOK_PUBLIC_KEY` asserted at boot
 - [ ] Webhook handlers deduplicate on `transactionId` plus `status`

package/skills/afriex-sdk/SKILL.md

@@ -3,7 +3,8 @@ name: afriex-sdk
 description: >
   Entry point for the Afriex Business API TypeScript SDK (@afriex/sdk) — the
   AfriexSDK / Afriex facade and its customers, transactions, paymentMethods,
-  balance, rates, checkout, and webhooks services. Covers installation,
+  paymentBatches, balance, rates, checkout, media, smeRegistration, and
+  webhooks services. Covers installation,
   AfriexSDKConfig including webhookPublicKey, choosing sandbox vs production,
   the end-to-end customer → payment method → transaction → webhook payout flow,
   and which sub-skill covers each service. Load when starting an Afriex
@@ -58,9 +59,12 @@ import it where needed — each construction builds a fresh HTTP client.
 | Register senders and recipients, submit KYC       | `afriex.customers`         | `afriex-customers`                |
 | Add bank, mobile money, or virtual account rails  | `afriex.paymentMethods`    | `afriex-payment-methods`          |
 | Send payouts, collect deposits, swap currencies   | `afriex.transactions`      | `afriex-transactions`             |
+| Pay many recipients in one call                   | `afriex.paymentBatches`    | `afriex-payment-batches`          |
 | Read wallet balances, fund a sandbox wallet       | `afriex.balance`           | `afriex-balance`                  |
 | Quote exchange rates                              | `afriex.rates`             | `afriex-rates`                    |
 | Host a payment page                               | `afriex.checkout`          | `afriex-checkout`                 |
+| Upload an invoice, a proof or a document          | `afriex.media`             | `afriex-media`                    |
+| Register for dedicated KES virtual accounts       | `afriex.smeRegistration`   | `afriex-sme-registration`         |
 | Verify inbound events, replay test events         | `afriex.webhooks`          | `afriex-webhooks`                 |
 | Configure transport, errors, retries              | `AfriexClient`, errors  | `afriex-core`                     |
 | Ship to production safely                         | —                       | `afriex-go-live`                  |