Quickstart

Get an access token

Exchange your API key for an access token. Pass your company reference in the path and your API key in the x-api-key header.

curl -X POST "https://shimi-waas-api-9493532b9281.herokuapp.com/api/v1/auth/generate-token/YOUR_COMPANY_REFERENCE" \
  -H "x-api-key: YOUR_API_KEY"

{
  "accessToken": "eyJhbGciOiJIUzI1NiIs...",
  "refreshToken": "eyJhbGciOiJIUzI1NiIs..."
}

Store both tokens securely. Each call to this endpoint replaces your previous refresh token.

Call the API with the token

Send the access token as a Bearer token on every other request. For example, to create a customer:

curl -X POST "https://shimi-waas-api-9493532b9281.herokuapp.com/api/v1/customer/" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "firstName": "Chiamaka",
    "lastName": "Okonkwo",
    "email": "[email protected]",
    "mobileNo": "+2348031234567",
    "bvn": "22345678901",
    "dob": "1992-03-14"
  }'

{
  "status": "success",
  "message": "Customer created successfully",
  "data": {
    "id": "cmg8x2k4p0001qz7h3n9d5v2a",
    "firstName": "Chiamaka",
    "lastName": "Okonkwo"
  }
}

The customer receives an OTP on their BVN-linked phone. Pass it to Generate Customer Account to create their dedicated bank account.

Refresh the token when it expires

Access tokens last 15 minutes. When a request returns 403 Invalid or expired access token, get a new one with your refresh token. No API key is needed.

curl -X POST "https://shimi-waas-api-9493532b9281.herokuapp.com/api/v1/auth/refresh-access-token/" \
  -H "Content-Type: application/json" \
  -d '{ "refreshToken": "YOUR_REFRESH_TOKEN" }'

{
  "accessToken": "eyJhbGciOiJIUzI1NiIs..."
}

Set up webhooks

Add your webhook URL in the Shimi dashboard (Settings → Webhook) so you’re told about deposits and payout outcomes as they happen. See Webhooks.