--- updatedAt: 2026-06-05T15:41:37.000Z agentTools: projectIndex: https://capera.readme.io/llms.txt --- # Integration Journey This guide walks you through the full path from zero to a live integration — account setup, your first API call, testing, and going to production. ## Overview ``` Create account → Get API key → Pick environment → Make first call → Set up webhooks → Test → Go live ``` *** ## Step 1: Create your Capera account Sign up at [dashboard.withcapera.com](https://dashboard.withcapera.com). Once your account is approved you will have access to both staging and production environments. *** ## Step 2: Get your API key In the dashboard, navigate to **Settings → API Keys** and generate a key. | Key prefix | Environment | Use for | | ---------- | ----------- | ----------------------- | | `sk_test_` | Staging | Development and testing | | `sk_live_` | Production | Real transactions | > **Keep your API key secret.** Store it in an environment variable, never in source code or version control. ```bash export CAPERA_API_KEY="sk_test_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" ``` All authenticated requests pass the key as a Bearer token: ```http Authorization: Bearer sk_test_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx ``` *** ## Step 3: Choose your environment | Environment | Base URL | | ----------- | ---------------------------------------- | | Staging | `https://staging-api.withcapera.com/b2b` | | Production | `https://api.withcapera.com/b2b` | Start on staging. It behaves identically to production but uses test money. Switch to production only when your integration is verified end-to-end. *** ## Step 4: Make your first API call Verify connectivity with the health check — no authentication required. ```bash curl https://staging-api.withcapera.com/b2b/health ``` ```json { "status": "healthy", "timestamp": "2024-01-15T10:00:00Z", "version": "v1.0.0", "service": "capera-b2b-api" } ``` Then fetch the list of supported banks to confirm your API key is working: ```bash curl https://staging-api.withcapera.com/b2b/v1/banks \ -H "Authorization: Bearer $CAPERA_API_KEY" ``` If you get a list of banks back, your key is valid and you are talking to the right environment. *** ## Step 5: Build your core flow Choose the flow that matches what you are building and follow the corresponding quickstart: ### Collecting payments If you need to receive money from your customers: 1. **Create a customer** — `POST /v1/customers` 2. **Generate a virtual account** — `POST /v1/virtual-accounts/ngn` (static) or `POST /v1/virtual-accounts/dynamic/ngn` (one-time) 3. **Share the account details** with the payer 4. **Receive a webhook** when the payment arrives (`deposit.success` or `customer.deposit.success`) See [Quickstart: Receive a Payment](./quickstart-receive-payment.md) for the full walkthrough. ### Sending payouts If you need to send money to bank accounts or mobile wallets: 1. **Get banks** — `GET /v1/banks` 2. **Resolve the account** — `GET /v1/bank/resolve` 3. **Initiate the transfer** — `POST /v1/transfers/initiate` 4. **Check status** — `GET /v1/transfers/:reference` or wait for the `transfer.success` / `transfer.failed` webhook See [Quickstart: Make a Transfer](./quickstart-make-transfer.md) for the full walkthrough. *** ## Step 6: Set up webhooks Webhooks are the recommended way to track payment and transfer outcomes. Instead of polling for status, Capera calls your endpoint the moment something changes. ### Register a webhook subscription ```bash curl -X POST https://staging-api.withcapera.com/b2b/v1/webhooks \ -H "Authorization: Bearer $CAPERA_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "url": "https://your-server.com/webhooks", "description": "Staging transfer and deposit events", "events": [ "transfer.success", "transfer.failed", "deposit.success", "customer.deposit.success" ], "environment": "sandbox" }' ``` The response includes a `secret` — store it immediately. It is only returned once and is used to verify webhook signatures. ```json { "id": "whsub_abc123def456", "secret": "whsec_a1b2c3d4e5f6...", "status": "active" } ``` ### Verify signatures Every webhook request from Capera includes an `X-Webhook-Signature` header. Always verify it before processing the payload. ``` X-Webhook-Signature: t=1705320000,v1=5257a869e7ecebeda32affa62cdca3fa51cad7e77a0e56ff536d0ce8e108d8bd ``` Verification steps: 1. Extract `t` (timestamp) and `v1` (signature) from the header 2. Construct the signed string: `{t}.{raw_request_body}` 3. Compute `HMAC-SHA256` of that string using your webhook secret 4. Compare your result to `v1` using a constant-time comparison ```javascript const crypto = require('crypto'); function verifyWebhookSignature(rawBody, signatureHeader, secret) { const parts = Object.fromEntries( signatureHeader.split(',').map(p => p.split('=')) ); const signed = `${parts.t}.${rawBody}`; const expected = crypto .createHmac('sha256', secret) .update(signed) .digest('hex'); return crypto.timingSafeEqual(Buffer.from(parts.v1), Buffer.from(expected)); } ``` ### Respond correctly Your endpoint must return a `2xx` status code within 30 seconds. Any other response triggers an automatic retry with exponential backoff (up to 5 attempts). *** ## Step 7: Handle errors and retries All error responses follow this format: ```json { "success": false, "error": { "code": "VALIDATION_ERROR", "message": "Amount must be greater than 0" }, "requestId": "req_abc123def456", "timestamp": "2024-01-15T10:00:00Z" } ``` **Retrying safely** Use the `reference` field as your idempotency key. If a transfer request fails due to a network error and you are unsure whether it was received, check the status by reference before retrying: ```bash curl https://staging-api.withcapera.com/b2b/v1/transfers/TRF-2024-001 \ -H "Authorization: Bearer $CAPERA_API_KEY" ``` If the transfer exists, do not initiate another one with the same reference. If it does not exist, it is safe to retry. **HTTP status codes** | Code | Meaning | | ----------- | ----------------------------------------------------- | | `200 / 201` | Success | | `400` | Bad request — check `error.message` for details | | `401` | Invalid or missing API key | | `404` | Resource not found | | `409` | Conflict — e.g. duplicate reference | | `429` | Rate limit exceeded — back off and retry | | `500` | Server error — safe to retry with exponential backoff | *** ## Step 8: Test your integration Before going live, run through these scenarios on staging: **Payments (inflow)** * [ ] Create a customer and generate a static virtual account * [ ] Generate a dynamic virtual account for a specific amount * [ ] Simulate a deposit and confirm your webhook receives `deposit.success` * [ ] Verify the webhook signature in your handler **Transfers (outflow)** * [ ] Resolve a test bank account * [ ] Initiate a transfer and confirm it reaches `SUCCESS` status * [ ] Confirm your webhook receives `transfer.success` * [ ] Attempt a duplicate reference and confirm only one transfer is created * [ ] Initiate a transfer to a non-existent account and confirm your error handling works **Webhooks** * [ ] Verify signature validation rejects tampered payloads * [ ] Confirm your endpoint returns `200` within 30 seconds * [ ] Test your retry handling by temporarily returning `500` *** ## Step 9: Go live Once your staging integration is verified: 1. Generate a `sk_live_` key in the dashboard 2. Update your environment variable to the live key 3. Point your webhook URL to your production endpoint and register a new subscription with `"environment": "production"` 4. Update your base URL to `https://api.withcapera.com/b2b` 5. Run a small real transaction end-to-end before ramping up volume *** ## Reference | Resource | Link | | ----------------------------- | ---------------------------------------------------------------- | | Quickstart: Receive a Payment | [quickstart-receive-payment.md](./quickstart-receive-payment.md) | | Quickstart: Make a Transfer | [quickstart-make-transfer.md](./quickstart-make-transfer.md) | | Authentication | [guides/authentication.md](../../docs/guides/authentication.md) | | Webhooks | [webhooks.md](../../docs/webhooks.md) | | Error Handling | [guides/errors.md](../../docs/guides/errors.md) | | API Reference | [docs/README.md](../../docs/README.md) | | Support | |