Skip to main content
A recipient is who you pay: their name, email and address. A destination is where you pay them: a bank account or mobile money wallet in one currency. One recipient can have several destinations, for example a GBP bank account and an NGN one. Scopes: recipients:read, recipients:write. Your account must be verified before you can add recipients (409 NOT_VERIFIED otherwise).

1. Create the recipient

  • type: individual needs firstName and lastName. type: business needs legalName, and optionally tradingName.
  • relationship is vendor, supplier, customer or employee. Pick the one that’s true: it’s part of a compliance record. Contractors are usually vendor.
  • address.stateOrProvince is 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:
The response lists the corridor’s 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.line1 and bank_address.city are both parts of the bank’s address. Send each one flat under fields, exactly as listed.
  • pattern is 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, wire and rtp for 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:
Send back the chosen bank’s 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

A field the network won’t accept comes back as 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/recipients lists recipients without their destinations.
  • GET /v1/recipients/{id} includes destinations. If it’s absent, they couldn’t be loaded just now: retry. An empty array means the recipient has none yet.