Payee field schemas are dynamic. Query the corridor before rendering a form instead of hardcoding the documentation's example.

Create Payees

Retrieve the Field Schema Before Rendering the Form

GET /v1/remit/payee-form-schema
    ?country_code=GB&currency=GBP&payment_method=LOCAL
    &clearing_system=FASTER%20PAYMENTS&entity_type=INDIVIDUAL

All five parameters are required, including entity_type, which an earlier version of this page omitted. We uppercase the first three parameters and entity_type; clearing_system is passed through with its original casing.

entity_type accepts INDIVIDUAL / COMPANY.

⚠ Omitting any parameter returns 400 invalid_fields. The response's fields

identifies the missing key; supply it and retry.

(Before 2026-08-13, missing parameters returned corridor_not_supported,

instructing callers to select a different corridor or payment method even though the corridor was valid.

Trying every corridor still failed. Incomplete input and unsupported corridor now have separate codes.)

The response is a field list evaluated for this specific corridor, not a fixed form:

Render the form from this contract, validate using its pattern / max_length / required values, and put the user's input unchanged into fields in POST /v1/remit/payees. Adding a country or clearing network, or tightening a format, then requires no code change on your side.

Three Field Attributes That Need Careful Interpretation

required: false does not mean inconsequential. We expose only fields that are mandatory, contribute to the fingerprint, or have ambiguous upstream documentation. A permanently unused field merely makes users think they missed something. Optional fields therefore often have in_fingerprint: true: whether they are supplied determines whether a new payee is created or an existing one is linked.

bind specifies a fixed value that must accompany this field when supplied. For GBP + FASTER PAYMENTS, for example, the 6-digit sort code is bank_details.routing_code_value1, and must be accompanied by bank_details.routing_code_type1: sort_code。

⚠ The corridor uniquely determines the routing-code type. Do not let the user choose it. A dropdown exposes a way

to change routing type, which the upstream system does not validate; the wrong type can route funds through the wrong clearing network.

A populated pending_confirm means ambiguous upstream wording is handled permissively. You may label the field optional, but must allow submission. Adding stricter validation from that wording can immediately block legitimate users.

⚠ Inputs use snake_case (country_code), while the response's corridor object uses camelCase

(countryCode). Do not feed response fields directly back into request parameters.

⚠ Do not hardcode a form from an example. If a corridor later requires another field,

users will complete your form only to receive an incomprehensible validation error after investing all that effort.

Save the Payee

POST /v1/remit/payees

At this stage we perform only format validation. Actual upstream registration occurs during dispatch, after funds have already been frozen from the member's balance.

⚠ This is an especially costly failure: missing a local format check causes more than a 400 response.

You discover the payee cannot be registered only after funds are locked. The order then stalls in dispatch,

the payee reaches an upstream terminal failure, and manual intervention is required.

Fetch the field schema by corridor. Do not guess, cache it overnight, or hardcode an example.

Verify

POST /v1/remit/payees/{id}/verify

For supported corridors, perform an account-name check to confirm that the account number and holder name match. There are three outcomes: match, mismatch, or name checking is unsupported for this corridor.

The third is not a failure. Treating it as one blocks all remittances through corridors without name-check support.

Editing a Payee Means Renaming It

PATCH /v1/remit/payees/{id}   { "nickname": "房东", "favorite": true }

The underlying payee identity—bank, account number, and account-holder name—is a platform-wide shared entity, keyed by a fingerprint of those details. A different account number means a different payee. Editing it in place would affect every linked member and the payee snapshots on completed orders.

Bank details therefore cannot be edited: create a new payee instead. Only the private nickname and favorite flag on your association can change. Label the action Rename, not Edit, and do not show a form users cannot modify.

Both fields are optional, but omitting both returns 400. This commonly indicates a misspelled key; a silent 200 would falsely suggest that the change succeeded.

Related Endpoints

• GET /v1/remit/payee-form-schema
• POST /v1/remit/payees
• POST /v1/remit/payees/{id}/verify
• DELETE /v1/remit/payees/{id}

Two Status Fields: Read the Right One

The response contains two status fields answering different questions:

⚠⚠ status is always active; this does not establish that the payee is usable.

Newly created payees are always active because our local enum only distinguishes enabled from disabled.

Using it as permission to place an order means failure may occur only after funds are locked.

Use upstream_status to determine usability.

upstream_status Values

⚠ not_submitted is not an error. Creating a payee makes no upstream calls,

because the payee is provider-independent. Do not display Verification failed.

To submit early, use POST /v1/remit/payees/{id}/verify.

⚠ unknown and not_submitted are different; do not merge them.

unknown means there is currently no available upstream route for this line: no provider is enabled,

or this member lacks a personal remittance subaccount. Enable the line first,

rather than asking the user to edit payee details.

name_mismatch

This is true when the same bank account was previously registered under a different account-holder name.

It does not block an order, but your risk controls should consider it. It is the closest signal we can provide that the account may not belong to this person.