On this page
Customers and authorizations
Create a customer or retrieve one by customer ID, email, or BVN. Use the returned ID for collection and authorization requests. Use the bank catalogue to look up institution codes. Use the direct debit bank list to check mandate coverage. Codes from another provider may use a different namespace.
Create a widget session#
Send POST /api/v1/collections/customer/{customer}/widget-sessions from your backend.
{
"customer_name": "Ada Okafor",
"accounts": [
{"bank_code": "058", "account_number": "0123456789", "is_primary": true},
{"bank_code": "044", "account_number": "0987654321"}
],
"required_accounts": 2,
"parent_origin": "https://lender.example",
"return_url": "https://lender.example/repayment-setup",
"expires_in_minutes": 30
}Set required_accounts to the minimum number of approvals you need. Include the primary account in that count if you designate one. If you omit the count, all supplied accounts are required. An optional institution_logo_url must be available over HTTPS. Treat widget_url and session_token as sensitive.
Embed the widget and verify the outcome#
Load /js/collection-widget-embed.js from the Collections origin and mount the widget using YanaCollections.mount({ container, url, onProgress, onContinue }). Set url to the returned widget_url. Set the session's parent_origin to the exact HTTPS origin of the page containing the iframe. Allow hosted checkout to open a popup. Destroy the widget when its container unmounts.
The widget sends yana.collections.progress and yana.collections.continue. For a custom iframe, check both the event origin and the iframe window. In either integration, verify current status on your backend through GET /api/v1/collections/widget-sessions/{session} before advancing.
A borrower may be able to continue while a mandate is awaiting activation. awaiting_activation means setup can be submitted while one or more required sources still need activation. completed indicates completed setup with active required sources. Check can_continue for borrower progression.
Choose direct debit or card#
Available authorization methods depend on institution settings and bank coverage. The widget starts with direct debit for supported banks when enabled. It can offer a card fallback after a direct debit retry when cards are enabled. Direct debit verifies the required account. Card checks use issuing-bank and available name evidence, so the card result cannot establish the full underlying account number.
For a server-led flow, use the card or direct debit initialize endpoint, send the borrower to hosted authorization, and verify by reference. Disclose any configured setup charge to the borrower. Keep card setup charges separate from loan repayments. Store provider references and authorization state. Card details belong in hosted checkout.
Receive widget webhooks#
When webhook delivery is enabled for your institution and approved HTTPS host, pass webhook_url at session creation. Save the returned secret securely. Verify X-Yana-Signature by computing HMAC-SHA256 over the raw body using that secret. Deduplicate with X-Yana-Event-Id. The event is collections.widget.updated. Updates can arrive after the borrower leaves or in a different order from the original state changes. Fetch the session for current state.