QUICKSTART

Send your first staging transfer

The shortest path from staging credentials to a completed test transfer.

Before you begin

After your MTO onboarding is approved, the CAPSEND MTO platform provides:

a staging client ID and client secret;
a managed staging wallet;
a place to configure your staging webhook URL; and
a webhook signing secret after the URL is configured.

Keep all secrets in your backend secret manager. Never put them in frontend code.

bash

export BASE_URL="https://staging.capsendimto.org/v1"
export CLIENT_ID="your_staging_client_id"
export CLIENT_SECRET="your_staging_client_secret"

1. Get an access token

POST /api/token

bash

curl --request POST "${BASE_URL}/api/token" \
  --header "Content-Type: application/json" \
  --data '{
    "clientId": "your_staging_client_id",
    "clientSecret": "your_staging_client_secret"
  }'

json

{
  "accessToken": "eyJhbGciOi...",
  "tokenType": "Bearer",
  "expiresIn": 3600
}

Use accessToken as Bearer ACCESS_TOKEN in the remaining requests. Reuse it until shortly before it expires.

2. Check your test wallet

GET /api/test-wallet

bash

curl "${BASE_URL}/api/test-wallet" \
  --header "Authorization: Bearer ACCESS_TOKEN"

json

{
  "id": "75eddfd6-d0d9-44fc-a0db-764c7d05e660",
  "currency": "USD",
  "balance": "10000.0000",
  "availableBalance": "10000.0000",
  "targetBalance": "10000.0000"
}

Use the returned currency for your staging transfer. CAPSEND automatically restores managed test funds when required, up to the wallet target.

3. Create a transfer

POST /transactions/createTransaction

Use a new UUID for every new transfer. Reuse that same UUID only when retrying the exact same request.

bash

curl --request POST "${BASE_URL}/transactions/createTransaction" \
  --header "Authorization: Bearer ACCESS_TOKEN" \
  --header "Content-Type: application/json" \
  --header "idempotency-key: 550e8400-e29b-41d4-a716-446655440000" \
  --data '{
    "amount": "100.0000",
    "currency": "USD",
    "transactionType": "PAYOUT",
    "crAccount": "0000014575",
    "narration": "Test transfer INV-1001",
    "country": "NG",
    "senderAddress": "100 Market Street",
    "senderName": "Jane Sender",
    "beneficiaryBankName": "Sudo Bank",
    "beneficiaryBankCode": "999998",
    "beneficiaryName": "John Beneficiary",
    "beneficiaryAddress": "12 Marina Road, Lagos",
    "stateCode": "LA",
    "externalReference": "INV-1001"
  }'

json

{
  "transactionId": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "reference": "CAP-8E5A19E0D3394E55A3CE4FBC876A514B",
  "status": "PENDING"
}

Store transactionId, reference, externalReference, and the idempotency key together. See the transfer reference for all fields and staging account details.

4. Receive the result

CAPSEND sends one of these signed terminal events to your configured webhook:

transaction.processed for a successful transfer;
transaction.failed for a failed transfer.

Verify the signature before changing customer or accounting state. See Webhooks.

5. Check status when needed

GET /transactions/get/:id

bash

curl "${BASE_URL}/transactions/get/7c9e6679-7425-40de-944b-e07fc1f90ae7" \
  --header "Authorization: Bearer ACCESS_TOKEN"

Use status lookup after a timeout, while recovering missed webhook processing, or during reconciliation. Webhooks should remain your normal source of asynchronous updates.

Your staging setup is complete when

token generation succeeds;
the staging wallet is visible;
a transfer returns a CAPSEND ID and reference;
your webhook verifies and stores the terminal event exactly once; and
the status endpoint agrees with the terminal event.