Lookup
Resolve account holder names before sending money.
Lookup API
The Lookup API lets you resolve the account holder name behind a mobile money number, bank account or Shika ID before initiating a payout, disbursement, or transfer. Use it to show recipients in your checkout or back-office flow before the user confirms the transfer.
Lookups are read-only — no money moves and no OTP is issued.
Verify a mobile money wallet
POST /v1/lookup/walletReturns the account holder name registered against a Ghana mobile money number.
Request
| Parameter | Type | Required | Description |
|---|---|---|---|
phone_number | string | Yes | 10-digit Ghana phone number (e.g. 0241234567) |
provider | string | No | mtn, telecel, or airteltigo. Auto-detected from the phone prefix if omitted. |
curl -X POST https://api.shikacreators.com/v1/lookup/wallet \
-H "Authorization: Bearer sk_live_..." \
-H "Content-Type: application/json" \
-d '{
"phone_number": "0241234567"
}'const res = await fetch('https://api.shikacreators.com/v1/lookup/wallet', {
method: 'POST',
headers: {
'Authorization': `Bearer ${process.env.SHIKA_SECRET_KEY}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
phone_number: '0241234567',
}),
});
const wallet = await res.json();import requests
response = requests.post(
'https://api.shikacreators.com/v1/lookup/wallet',
headers={'Authorization': f'Bearer {SECRET_KEY}'},
json={'phone_number': '0241234567'},
)
wallet = response.json()Response
{
"object": "wallet_verification",
"verified": true,
"account_name": "JOHN DOE",
"phone_number": "0241234567",
"provider": "mtn"
}Verify a Shika ID
POST /v1/lookup/shika-idReturns the consumer or cash agent behind a Shika ID (the short SHK12345 id a Shika Creators user reads out or shows on screen). A verified: true answer means a shika_wallet payout or disbursement to that ID will be accepted: the account is active and its wallet or float can receive money. A merchant's Shika ID is rejected.
Request
| Parameter | Type | Required | Description |
|---|---|---|---|
shika_id | string | Yes | The recipient's Shika ID, e.g. SHK12345. Case does not matter. |
curl -X POST https://api.shikacreators.com/v1/lookup/shika-id \
-H "Authorization: Bearer sk_live_..." \
-H "Content-Type: application/json" \
-d '{
"shika_id": "SHK12345"
}'const res = await fetch('https://api.shikacreators.com/v1/lookup/shika-id', {
method: 'POST',
headers: {
'Authorization': `Bearer ${process.env.SHIKA_SECRET_KEY}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({ shika_id: 'SHK12345' }),
});
const consumer = await res.json();import requests
response = requests.post(
'https://api.shikacreators.com/v1/lookup/shika-id',
headers={'Authorization': f'Bearer {SECRET_KEY}'},
json={'shika_id': 'SHK12345'},
)
consumer = response.json()Response
{
"object": "shika_id_verification",
"verified": true,
"shika_id": "SHK12345",
"recipient_type": "consumer",
"account_id": "acc_abc123def456",
"account_name": "Ama Mensah",
"masked_phone": "024****567"
}| Field | Description |
|---|---|
recipient_type | consumer or cash_agent |
account_id | acc_... for a consumer, cag_... for a cash agent |
account_name | The consumer's name, or the agent's business name |
Either shika_id or account_id can then be used as the destination of a payout or disbursement.
Verify a bank account
POST /v1/lookup/bank-accountReturns the account holder name registered against a Ghana bank account. Use GET /v1/lookup/banks to find the right bank_code.
Request
| Parameter | Type | Required | Description |
|---|---|---|---|
account_number | string | Yes | Bank account number |
bank_code | string | Yes | Bank code from /v1/lookup/banks |
curl -X POST https://api.shikacreators.com/v1/lookup/bank-account \
-H "Authorization: Bearer sk_live_..." \
-H "Content-Type: application/json" \
-d '{
"account_number": "1234567890",
"bank_code": "030100"
}'const res = await fetch('https://api.shikacreators.com/v1/lookup/bank-account', {
method: 'POST',
headers: {
'Authorization': `Bearer ${process.env.SHIKA_SECRET_KEY}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
account_number: '1234567890',
bank_code: '030100',
}),
});
const account = await res.json();Response
{
"object": "bank_account_verification",
"verified": true,
"account_name": "JOHN DOE",
"account_number": "1234567890",
"bank_code": "030100"
}List supported banks
GET /v1/lookup/banksReturns the list of banks supported for bank transfers and bank-account verification.
The bank_code values are specific to your account. Accounts are routed to one of
several banking partners, and each partner identifies banks with its own codes. Read
this list rather than hardcoding codes, and re-read it if bank transfers start being
rejected. Caching it for a day is fine.
curl https://api.shikacreators.com/v1/lookup/banks \
-H "Authorization: Bearer sk_live_..."const res = await fetch('https://api.shikacreators.com/v1/lookup/banks', {
headers: { 'Authorization': `Bearer ${process.env.SHIKA_SECRET_KEY}` },
});
const { data: banks } = await res.json();Response
{
"object": "list",
"data": [
{
"bank_name": "Access Bank",
"short_name": "ACCESS",
"bank_code": "030100",
"sort_code": "030100"
}
],
"total": 1
}Errors
| Code | Description |
|---|---|
invalid_phone_number | Phone number is not a valid Ghana mobile number, or doesn't match the provider you supplied. |
wallet_verification_failed | The provider could not resolve the wallet (number not registered, network unreachable, etc.). |
bank_verification_failed | The bank could not resolve the account number (wrong bank code, account doesn't exist, etc.). |
invalid_shika_id | shika_id is not in the form SHK12345. |
shika_id_not_found | No consumer or cash agent has that Shika ID. |
shika_id_not_payable | The Shika ID belongs to a merchant, which cannot be paid this way. |
subagent_not_payable | The Shika ID belongs to a sub-agent. Pay the main agent instead. |
account_not_found | The consumer or cash agent is not active. |
wallet_not_active | The recipient's wallet or float is frozen or suspended. |
validation_error | Request body failed schema validation. |