Integration Journey

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. 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.

Keep your API key secret. Store it in an environment variable, never in source code or version control.

export CAPERA_API_KEY="sk_test_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

All authenticated requests pass the key as a Bearer token:

Authorization: Bearer sk_test_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Step 3: Choose your environment

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.

curl https://staging-api.withcapera.com/b2b/health

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

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 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 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

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.

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

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:

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

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

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