> ## Documentation Index
> Fetch the complete documentation index at: https://docs.stablestack.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Financial Institutions

> Use StableStack to issue stablecoin wallets, process bulk payouts, and deliver cross-border remittances for your customers.

## Overview

Banks, microfinance institutions, neobanks, and remittance platforms can embed StableStack to offer their end-customers stablecoin accounts, cross-border payouts, and real-time transaction visibility — without building blockchain infrastructure from scratch. StableStack handles custody, rails, and compliance tooling so you can focus on your product.

***

## Core Flow

<Steps>
  <Step title="KYC your customers and register them">
    Register each end-customer in StableStack with the appropriate customer type. Upload KYC documents to satisfy compliance requirements.

    **Create a customer:**

    ```http theme={null}
    POST /individual-customers
    ```

    ```json theme={null}
    {
      "first_name": "Amara",
      "last_name": "Osei",
      "email": "amara.osei@example.com",
      "country": "Ghana",
      "phone": "+233244000000"
    }
    ```

    **Upload KYC documents:**

    ```http theme={null}
    POST /customers/{customer_id}/kyc
    ```

    Upload identity documents (passport, national ID, utility bill) as multipart form data.
  </Step>

  <Step title="Provision stablecoin wallets per customer">
    Issue a dedicated stablecoin wallet to each customer on your platform. The wallet address is unique to the customer and can be used to receive inbound deposits.

    ```http theme={null}
    POST /wallets
    ```

    ```json theme={null}
    {
      "customer_id": "CUSTOMER_ID",
      "currency": "USDC",
      "network": "erc20",
      "description": "Customer USDC account"
    }
    ```
  </Step>

  <Step title="Manage customer payout beneficiaries">
    Let customers save their preferred bank accounts or external wallets for fast repeat payouts.

    **Add a bank beneficiary:**

    ```http theme={null}
    POST /payout/methods/banks
    ```

    ```json theme={null}
    {
      "customer_id": "CUSTOMER_ID",
      "account_number": "0987654321",
      "bank_code": "000013",
      "bank_name": "GTBank",
      "currency": "NGN",
      "country": "Nigeria",
      "recipient_name": "Amara Osei"
    }
    ```

    **Add a wallet beneficiary:**

    ```http theme={null}
    POST /payout/methods/wallets
    ```

    ```json theme={null}
    {
      "customer_id": "CUSTOMER_ID",
      "address": "RecipientWalletAddressHere",
      "network": "erc20",
      "currency": "USDC",
      "recipient_name": "Amara Osei"
    }
    ```
  </Step>

  <Step title="Process customer payouts">
    Execute withdrawals on behalf of customers — to local bank accounts (remittance) or external stablecoin wallets.

    **Bank payout (remittance):**

    ```http theme={null}
    POST /payouts/banks
    ```

    ```json theme={null}
    {
      "customer_id": "CUSTOMER_ID",
      "currency": "USDC",
      "account_number": "0987654321",
      "bank_name": "GTBank",
      "bank_code": "000013",
      "amount": "500",
      "recipient_name": "Amara Osei",
      "recipient_currency": "NGN",
      "recipient_country": "Nigeria"
    }
    ```

    **Stablecoin wallet payout:**

    ```http theme={null}
    POST /payouts/wallets
    ```

    ```json theme={null}
    {
      "customer_id": "CUSTOMER_ID",
      "currency": "USDC",
      "address": "RecipientWalletAddressHere",
      "amount": 200,
      "network": "erc20",
      "recipient_name": "Amara Osei"
    }
    ```
  </Step>

  <Step title="Fetch customer transaction history">
    Provide customers with a full transaction history or pull records for compliance reporting.

    ```http theme={null}
    GET /customers/transactions/by_customer_id/{customer_id}
    ```

    For a specific transaction:

    ```http theme={null}
    GET /customers/transactions/by_txid/{transaction_id}
    GET /customers/transactions/by_ref_id/{reference_id}
    ```
  </Step>

  <Step title="Monitor all activity with webhooks">
    Configure webhooks to keep your core banking system in sync with every wallet event and payout status change.

    **Key events to subscribe to:**

    * `wallet.transaction.inbound` — Credit a customer's account when funds arrive
    * `wallet.transaction.outbound` — Debit a customer's account when funds leave
    * `payout.completed` — Confirm successful remittance delivery
    * `payout.failed` — Trigger retry logic or customer notification
  </Step>
</Steps>

***

## Customer Account Architecture

A typical financial institution account structure on StableStack:

```
Institution (Merchant)
├── Merchant Wallets     → Liquidity pools (USDC / ERC20, USDC / Polygon)
└── Customers
    ├── Customer A
    │   ├── Wallet: USDC / ERC20
    │   ├── Payout Method: GTBank NGN
    │   └── Transactions: history
    └── Customer B
        ├── Wallet: USDC / Polygon
        └── Payout Method: External USDC wallet
```

***

## Compliance Touchpoints

| Requirement          | StableStack Capability                                                  |
| -------------------- | ----------------------------------------------------------------------- |
| Customer identity    | `POST /individual-customers` or `POST /business-customers` + KYC upload |
| Transaction audit    | `GET /transactions` with full history                                   |
| Payout traceability  | Reference IDs on every payout                                           |
| Real-time monitoring | Webhook events for every state change                                   |

***

## Key APIs Used

| Endpoint                                          | Purpose                                |
| ------------------------------------------------- | -------------------------------------- |
| `POST /individual-customers`                      | Register an individual customer        |
| `POST /business-customers`                        | Register a business customer           |
| `POST /customers/{customer_id}/kyc`               | Upload KYC documents                   |
| `GET /customers`                                  | List all customers                     |
| `POST /wallets`                                   | Issue a wallet to a customer           |
| `GET /wallets/{customer_id}/customer`             | View all wallets for a customer        |
| `POST /payout/methods/banks`                      | Save a customer's bank beneficiary     |
| `POST /payout/methods/wallets`                    | Save a customer's wallet beneficiary   |
| `GET /payout/methods/{payout_method_id}`          | Retrieve a beneficiary                 |
| `POST /payouts/banks`                             | Execute a bank payout for a customer   |
| `POST /payouts/wallets`                           | Execute a wallet payout for a customer |
| `GET /payouts/fees`                               | Pre-check payout fees                  |
| `GET /customers/transactions/by_customer_id/{id}` | Full transaction history per customer  |

***

## Next Steps

* [Authentication](/authentication) — Get your API key
* [Webhooks](/webhooks/introduction) — Set up real-time event notifications
* [Webhook Security](/webhooks/security) — Verify webhook signatures
* [Supported Currencies](/coverage/currencies) — Available corridors