Financial Institutions

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

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:

POST /individual-customers

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

Upload KYC documents:

POST /customers/{customer_id}/kyc

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

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.

POST /wallets

{
  "customer_id": "CUSTOMER_ID",
  "currency": "USDC",
  "network": "erc20",
  "description": "Customer USDC account"
}

Manage customer payout beneficiaries

Let customers save their preferred bank accounts or external wallets for fast repeat payouts.Add a bank beneficiary:

POST /payout/methods/banks

{
  "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:

POST /payout/methods/wallets

{
  "customer_id": "CUSTOMER_ID",
  "address": "RecipientWalletAddressHere",
  "network": "erc20",
  "currency": "USDC",
  "recipient_name": "Amara Osei"
}

Process customer payouts

Execute withdrawals on behalf of customers — to local bank accounts (remittance) or external stablecoin wallets.Bank payout (remittance):

POST /payouts/banks

{
  "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:

POST /payouts/wallets

{
  "customer_id": "CUSTOMER_ID",
  "currency": "USDC",
  "address": "RecipientWalletAddressHere",
  "amount": 200,
  "network": "erc20",
  "recipient_name": "Amara Osei"
}

Fetch customer transaction history

Provide customers with a full transaction history or pull records for compliance reporting.

GET /customers/transactions/by_customer_id/{customer_id}

For a specific transaction:

GET /customers/transactions/by_txid/{transaction_id}
GET /customers/transactions/by_ref_id/{reference_id}

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

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 — Get your API key
Webhooks — Set up real-time event notifications
Webhook Security — Verify webhook signatures
Supported Currencies — Available corridors

Get Started

Webhooks

Libraries

Coverage

Use Cases

Prohibited

Financial Institutions

Overview

Core Flow

Customer Account Architecture

Compliance Touchpoints

Key APIs Used

Next Steps

​Overview

​Core Flow

​Customer Account Architecture

​Compliance Touchpoints

​Key APIs Used

​Next Steps

Overview

Core Flow

Customer Account Architecture

Compliance Touchpoints

Key APIs Used

Next Steps