> ## Documentation Index > Fetch the complete documentation index at: https://docs.onecluster.co/llms.txt > Use this file to discover all available pages before exploring further. # Create Collection Account > Creates a virtual account specifically for receiving money (collections). When someone sends money to this account number, you receive a webhook notification with the payment details in real time. **Use cases:** - Assign each customer their own unique receiving account (STATIC) - Generate a payment link that expires after a set time (DYNAMIC) ## OpenAPI ````yaml POST /api/v1/collections/accounts openapi: 3.0.3 info: title: Union Bank BaaS API version: '1.0' description: > **Union Bank Nigeria, Banking as a Service (BaaS) Platform** Build financial products on top of Union Bank's core banking infrastructure. This API gives your application the ability to open virtual accounts, initiate payments, collect money, verify identities, and manage webhooks, all in one place. ## Before You Start You must complete the **partner onboarding journey** before your API keys work: 1. Register at [ubn-ui.onecluster.co](https://ubn-ui.onecluster.co) 2. Verify your business email 3. Upload your business documents (KYB) 4. Pass identity verification (KYC) 5. Receive your sandbox API key ## Base URLs | Environment | Base URL | |-------------|----------| | Sandbox (for testing) | `https://api-partner.onecluster.co` | | Production (for live apps) | `https://api.onecluster.co` | ## How to Authenticate Add your API key to every request as a header: ``` Authorization: ApiKey ubn_sb_your_key_here ``` For payments, you also need to attach a **digital signature** (HMAC-SHA256) and an **mTLS client certificate**. See the [Authentication Guide](/api-reference/authentication) for details. ## Standard Request Headers | Header | Required | Description | |--------|----------|-------------| | `Authorization` | Yes | Your API key. Format: `ApiKey ubn_sb_xxx` | | `X-Correlation-ID` | No | A UUID you choose, used to trace this request in logs. We generate one if you omit it. | | `X-Idempotency-Key` | Yes (write ops) | A UUID you choose. If you send the same request twice with the same key, we return the original result, not a duplicate. | | `X-Signature` | Yes (payments, KYC) | HMAC-SHA256 signature of the request body. See Authentication guide. | ## Standard Response Headers | Header | Description | |--------|-------------| | `X-Correlation-ID` | The trace ID for this request (echoed from your request or generated by us) | | `X-Quota-Remaining` | How many API calls you have left in this billing period | | `X-Quota-Limit` | Your total API call quota for this billing period | | `X-Quota-Reset` | When your quota resets (Nigeria time, WAT +01:00) | | `X-Circuit-Breaker-Open` | Present and `true` if our system is temporarily pausing requests to protect stability | | `X-Key-Rotation-Warning` | Present when your API key is about to expire (within 72 hours of rotation) | contact: name: UBN BaaS Support email: baas-support@unionbank.ng url: https://dash.onecluster.co/resources/support license: name: Proprietary url: https://unionbank.ng/terms servers: - url: https://api-partner.onecluster.co description: Sandbox - use this for testing. No real money moves. - url: https://api.onecluster.co description: Production - live environment. Real transactions. security: - ApiKeyAuth: [] tags: - name: Accounts description: Open and manage virtual bank accounts - name: Payments description: Send money to any Nigerian bank account - name: Collections description: Receive money into virtual collection accounts - name: KYC description: Verify customer identities (BVN, NIN, CAC) - name: Health description: Check if the API is up and running paths: /api/v1/collections/accounts: post: tags: - Collections summary: Create a collection account description: > Creates a virtual account specifically for receiving money (collections). When someone sends money to this account number, you receive a webhook notification with the payment details in real time. **Use cases:** - Assign each customer their own unique receiving account (STATIC) - Generate a payment link that expires after a set time (DYNAMIC) operationId: createCollectionAccount parameters: - $ref: '#/components/parameters/CorrelationId' - $ref: '#/components/parameters/IdempotencyKey' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreateCollectionAccountRequest' example: partnerId: 9a1b2c3d-4e5f-6a7b-8c9d-0e1f2a3b4c5d accountType: STATIC responses: '201': description: Collection account created content: application/json: schema: $ref: '#/components/schemas/SuccessEnvelope' example: success: true responseCode: '00' message: Collection account created data: accountNumber: '9876543210' bankCode: '032' bankName: Union Bank of Nigeria accountType: STATIC '401': $ref: '#/components/responses/Unauthorized' components: parameters: CorrelationId: name: X-Correlation-ID in: header required: false description: > A UUID v4 you generate to trace this request through our systems. If you don't provide one, we generate it for you. Always include it in support requests, it helps us find your request in logs. schema: type: string format: uuid example: 7f3a9c21-4e8b-4a12-b6d1-3c8a7f2e1b09 IdempotencyKey: name: X-Idempotency-Key in: header required: true description: > A UUID you generate. If you send the same request twice with the same key (within 24 hours), we return the original response, not a duplicate action. Generate a new UUID for every new operation. schema: type: string format: uuid example: 550e8400-e29b-41d4-a716-446655440000 schemas: CreateCollectionAccountRequest: type: object required: - partnerId - accountType properties: partnerId: type: string format: uuid accountType: type: string enum: - STATIC - DYNAMIC default: STATIC expiryHours: type: integer description: Required when `accountType` is `DYNAMIC` SuccessEnvelope: type: object description: Standard response wrapper for all successful API calls required: - success - responseCode - message - data properties: success: type: boolean description: Always `true` for successful responses example: true responseCode: type: string description: '`00` means success' example: '00' message: type: string description: Human-readable description of the result example: Request processed successfully data: type: object description: The actual response data (varies by endpoint) ProblemDetails: type: object description: > Standard error response following [RFC 7807](https://tools.ietf.org/html/rfc7807). All errors use this format. required: - type - title - status - detail properties: type: type: string format: uri description: A link to the specific error type documentation example: https://api.onecluster.co/errors/insufficient-funds title: type: string description: Short, human-readable error name example: Insufficient Funds status: type: integer description: HTTP status code example: 422 detail: type: string description: Full explanation of what went wrong and how to fix it example: >- The account balance is ₦0.00. You need at least ₦50,000.00 to complete this transfer. instance: type: string format: uri description: The API path where the error occurred example: /api/v1/payments/transfer correlationId: type: string format: uuid description: The trace ID, include this when contacting support code: type: string description: Machine-readable error code example: INSUFFICIENT_FUNDS responses: Unauthorized: description: > Authentication failed. Check that your `Authorization` header is correct. Format: `ApiKey ubn_sb_your_key_here` content: application/problem+json: schema: $ref: '#/components/schemas/ProblemDetails' securitySchemes: ApiKeyAuth: type: apiKey in: header name: Authorization description: | Your API key, formatted as: `ApiKey ubn_sb_your_key_here` - Sandbox keys start with `ubn_sb_` - Production keys start with `ubn_pk_` - Never use production keys during testing, they will charge real money ````