# x-bridge

## Docs

- [Exchange keyId + secret for a Bearer token](https://docs.xbridge.co.tz/api-reference/auth/exchange-keyid-+-secret-for-a-bearer-token.md): Returns a short-lived (~1h) JWT used as `Authorization: Bearer <token>` on all other calls. Each service (BaaS core and Collections gateway) issues its own token from its own key pair.
- [List collection transactions](https://docs.xbridge.co.tz/api-reference/collections/list-collection-transactions.md): Paginated, newest first.
- [Poll collection status](https://docs.xbridge.co.tz/api-reference/collections/poll-collection-status.md): Poll until COMPLETED (or a terminal failure). Supported for ClickPesa rails (Airtel Money, Mixx by Yas, Halotel).
- [Trigger a mobile (USSD) collection](https://docs.xbridge.co.tz/api-reference/collections/trigger-a-mobile-ussd-collection.md): Initiates a USSD push to the payer's phone. Uses the Collections gateway server + its own Bearer token. `transactionId` is your own unique reference (used to poll status and as an idempotency key).
- [Activate a customer](https://docs.xbridge.co.tz/api-reference/kyc/activate-a-customer.md): A customer must be ACTIVE before they can hold wallets or loans.
- [Get customer by ID](https://docs.xbridge.co.tz/api-reference/kyc/get-customer-by-id.md)
- [Get customer by phone](https://docs.xbridge.co.tz/api-reference/kyc/get-customer-by-phone.md)
- [List customers](https://docs.xbridge.co.tz/api-reference/kyc/list-customers.md): Paginated list. Documented from the API surface; not exercised by the reference integration.
- [Submit KYC documents](https://docs.xbridge.co.tz/api-reference/kyc/submit-kyc-documents.md)
- [Upsert a customer](https://docs.xbridge.co.tz/api-reference/kyc/upsert-a-customer.md): Creates or updates a customer and syncs them to the core banking engine. Returns the `customerId` to use everywhere else.
- [Approve a loan](https://docs.xbridge.co.tz/api-reference/lending/approve-a-loan.md)
- [Disburse a loan](https://docs.xbridge.co.tz/api-reference/lending/disburse-a-loan.md)
- [Disburse a loan to its linked wallet](https://docs.xbridge.co.tz/api-reference/lending/disburse-a-loan-to-its-linked-wallet.md): Credits the linked wallet and syncs the local balance. Use for loans created with a linked/auto-provisioned wallet.
- [Get a shareable pay link](https://docs.xbridge.co.tz/api-reference/lending/get-a-shareable-pay-link.md)
- [Get active repayment schedule](https://docs.xbridge.co.tz/api-reference/lending/get-active-repayment-schedule.md)
- [Get loan](https://docs.xbridge.co.tz/api-reference/lending/get-loan.md): Documented from the API surface. Note: this response currently reflects core-engine fields (integer `id`, `status.value` like `loanStatusType.active`).
- [Get loan product by code](https://docs.xbridge.co.tz/api-reference/lending/get-loan-product-by-code.md): Documented from the API surface; not exercised by the reference integration.
- [List loan products](https://docs.xbridge.co.tz/api-reference/lending/list-loan-products.md)
- [List payment types](https://docs.xbridge.co.tz/api-reference/lending/list-payment-types.md): Returns the `paymentTypeId` values accepted by the repayment endpoint.
- [Originate a loan](https://docs.xbridge.co.tz/api-reference/lending/originate-a-loan.md): Creates a loan application. Three wallet-linking strategies: (A) no wallet, (B) `linkWalletId` to attach an existing wallet, (C) `createWalletProductCode` to auto-provision a wallet and set up an auto-sweep standing instruction for repayments.
- [Preview a repayment schedule](https://docs.xbridge.co.tz/api-reference/lending/preview-a-repayment-schedule.md): Calculates a schedule without creating a loan. Same body as Originate a loan.
- [Record a repayment](https://docs.xbridge.co.tz/api-reference/lending/record-a-repayment.md): Records a repayment your gateway already collected. `receiptNumber` acts as your idempotency key.
- [Submit & verify an externally-collected repayment](https://docs.xbridge.co.tz/api-reference/lending/submit-&-verify-an-externally-collected-repayment.md): Bridge polls the payment gateway to verify the payment happened and the amount matches before recording it. Idempotent on `gatewayReference`. Recommended over the raw repayment endpoint.
- [Activate a wallet](https://docs.xbridge.co.tz/api-reference/wallets/activate-a-wallet.md)
- [Approve a wallet](https://docs.xbridge.co.tz/api-reference/wallets/approve-a-wallet.md)
- [Commit (capture) a hold](https://docs.xbridge.co.tz/api-reference/wallets/commit-capture-a-hold.md)
- [Get wallet](https://docs.xbridge.co.tz/api-reference/wallets/get-wallet.md): Includes balance, status, and any linked loan.
- [List wallet products](https://docs.xbridge.co.tz/api-reference/wallets/list-wallet-products.md)
- [List wallet transactions](https://docs.xbridge.co.tz/api-reference/wallets/list-wallet-transactions.md): Returns two arrays: **`items`** — the x-bridge transaction view; build against this. **Avoid `fineractItems`** (the raw core-engine transactions) **for now** — lean on `items`.
- [List wallets for a customer](https://docs.xbridge.co.tz/api-reference/wallets/list-wallets-for-a-customer.md)
- [Open a wallet](https://docs.xbridge.co.tz/api-reference/wallets/open-a-wallet.md): `businessId` is taken from your token. Newly opened wallets must be approved and activated before use.
- [Release (cancel) a hold](https://docs.xbridge.co.tz/api-reference/wallets/release-cancel-a-hold.md)
- [Reserve funds (escrow hold)](https://docs.xbridge.co.tz/api-reference/wallets/reserve-funds-escrow-hold.md): Places a hold for the hold-and-capture pattern. Returns a `transactionId` to commit or release.
- [Submit & verify a wallet deposit](https://docs.xbridge.co.tz/api-reference/wallets/submit-&-verify-a-wallet-deposit.md): Bridge verifies the deposit on the gateway before crediting the wallet. Idempotent on `gatewayReference`.
- [Authentication](https://docs.xbridge.co.tz/authentication.md): Exchange your API keys for a short-lived Bearer token, and recover from expiry cleanly.
- [Conventions](https://docs.xbridge.co.tz/concepts/conventions.md): IDs, idempotency, environments, and dates.
- [Errors & status codes](https://docs.xbridge.co.tz/concepts/errors.md): What each error means, why it happens, and how to fix it.
- [First call in 5 minutes](https://docs.xbridge.co.tz/getting-started.md): Go from API keys to a real money event — disburse a loan into a wallet — without leaving your terminal.
- [Bridge — Build with banks, ship like a startup](https://docs.xbridge.co.tz/index.md): Launch wallets, lending, and payment collections via one API while a bank/FSP keeps custody and compliance.
- [Connect your AI agent (MCP)](https://docs.xbridge.co.tz/mcp.md): These docs are a hosted MCP server. Connect Claude Code, Cursor, or any MCP client and build x-bridge into your app by describing what you want.
- [Onboarding](https://docs.xbridge.co.tz/onboarding.md): How businesses join Bridge: sandbox access, credentials, products, and going live.
- [BNPL (Buy Now, Pay Later)](https://docs.xbridge.co.tz/recipes/bnpl.md): Hold a down-payment in escrow, finance the rest with a wallet-linked loan, disburse, then capture the down-payment.
- [Payment collections](https://docs.xbridge.co.tz/recipes/collections.md): Trigger a mobile (USSD) collection, poll until it completes, then post the verified payment.
- [Customer onboarding (KYC)](https://docs.xbridge.co.tz/recipes/kyc-onboarding.md): Create a customer, submit KYC, and activate them — the prerequisite for every wallet and loan.
- [Lending](https://docs.xbridge.co.tz/recipes/lending.md): Create a loan, preview its schedule, disburse, and record repayments.
- [Wallets](https://docs.xbridge.co.tz/recipes/wallets.md): Open a wallet, fund it with a verified deposit, and run an escrow hold-and-capture.

## OpenAPI Specs

- [openapi](https://docs.xbridge.co.tz/api-reference/openapi.json)

## Optional

- [Dashboard](https://app.bridge.usereli.tech)
- [Support](mailto:hello@xbridge.co.tz)