recipients:read, recipients:write. Your account must be verified before you can add recipients (409 NOT_VERIFIED otherwise).
1. Create the recipient
type: individualneedsfirstNameandlastName.type: businessneedslegalName, and optionallytradingName.relationshipisvendor,supplier,customeroremployee. Pick the one that’s true: it’s part of a compliance record. Contractors are usuallyvendor.address.stateOrProvinceis required. Payment networks can accept a recipient without one and then refuse every payment to them.phone, if you send it, must be in international format (for example+2348012345678).
2. Find out what the destination needs
What a bank account looks like depends on the corridor: a sort code in the UK, a routing number and account type in the US, an IBAN in the eurozone, a bank and account number in Nigeria. Ask instead of hardcoding:schemes and fields. Each field has a key, a label, whether it’s required, and optionally a pattern and an example. Call it without method and currency to list every supported corridor.
- Keys with a dot are parts of one nested field.
bank_address.line1andbank_address.cityare both parts of the bank’s address. Send each one flat underfields, exactly as listed. patternis a hint. Use it to catch typos, but don’t make your checks stricter than it; the payment network has the final say.- More than one scheme (for example
ach,wireandrtpfor USD) means you must choose one.
3. Pick the bank
Where a corridor needs a bank, list the country’s banks and let the user choose:bankId, whole. Don’t parse it, and don’t also send a bank code or bank name: Talescria fills in whatever the corridor needs. An empty banks list is normal for some countries (the UK routes on sort codes), so fall back to the typed fields.
4. Add the destination
422 UNSUPPORTED, with message naming the field.
What Talescria keeps
Account numbers, IBANs and phone numbers are passed to the payment network and not stored by Talescria. When you read a recipient, each destination shows:
Keep your own copy of anything you need to show in full. Identity document numbers work the same way: you get back the document type, issuing country and last four.
Reading recipients
GET /v1/recipientslists recipients without their destinations.GET /v1/recipients/{id}includesdestinations. If it’s absent, they couldn’t be loaded just now: retry. An empty array means the recipient has none yet.