Identity
Check an IBAN's checksum and resolve a mobile number to its channel.
Identity answers questions about a destination before you send money to it. Two endpoints, both
POST, both synchronous, both free of side effects.
| Method | Endpoint | What it does |
|---|---|---|
POST | /identity/validate | Checks an IBAN's structure, length and mod-97 checksum. |
POST | /identity/resolve | Resolves a mobile number to its channel and account holder. |
Two conditions apply
Identity needs a private key (sk.) or a restricted key carrying identity.write, and a paid
plan: starter, growth, scale or business. Any other plan gets a 403 telling you to
upgrade.
Validate an IBAN
This runs entirely on our side, no bank is contacted. It checks three things in order: the format (two letters, two digits, then alphanumerics), the length expected for that country, and the ISO 13616 mod-97 checksum. A valid checksum means the IBAN is well-formed, not that the account exists.
https://api.wajub.com/identity/validateibanstringrequiredtypestringoptionaliban is accepted today.curl https://api.wajub.com/identity/validate \
-H "Authorization: $WAJUB_API_KEY" \
-H "Content-Type: application/json" \
-d '{ "iban": "FR14 2004 1010 0505 0001 3M02 606" }'The response is flat, with no envelope. iban comes back normalised, which is the form you
should store:
When the IBAN is rejected, message names the reason so you can put it straight in front of the
user:
The five possible messages:
message | Cause |
|---|---|
IBAN is too short. | Fewer than four characters. |
IBAN format is invalid (expected 2 letters, 2 digits, then alphanumeric). | Wrong shape. |
IBAN length must be N characters for country XX. | Known country, wrong length. |
IBAN length must be between 15 and 34 characters. | Country not in our length table. |
IBAN checksum is invalid. | Shape and length fine, mod-97 fails. |
A rejection is still a 200
valid: false is a successful call with a negative answer, not an error. Branch on valid,
not on the status code.
Resolve a mobile number
Resolve takes a number and a channel and returns the payment method it would create: the resolved
channel, a provisional method id, and the account holder's name. issuer is present only when the
channel records one, so read it defensively.
https://api.wajub.com/identity/resolveaccount_numberstringrequiredchannelstringrequiredcm.mtn or cm.orange, or cm.mobile to let Wajub pick between the two from the number itself.countrystringrequiredtypestringrequiredmobile is accepted today.curl https://api.wajub.com/identity/resolve \
-H "Authorization: $WAJUB_SANDBOX_KEY" \
-H "Content-Type: application/json" \
-d '{
"account_number": "670000000",
"channel": "cm.mobile",
"country": "CM",
"type": "mobile"
}'cm.mobile was resolved to cm.mtn here, from the number's prefix:
A number whose operator we cannot identify is a 422:
Resolve is sandbox only
In live, POST /identity/resolve answers 501 Not Implemented with
Identify resolve is only available in sandbox. Use a sandbox API key. The sandbox
implementation derives the channel from the number prefix and returns a placeholder holder
name; there is no operator lookup behind it yet. Build against it, but do not put the name it
returns in front of a customer in production.
POST /identity/validate has no such restriction: the mod-97 check is arithmetic and works
identically in both environments.