Skip to content
Last updated

Recipient verification

To optimise payment success rates and reduce returned transfer incidents, Wise performs a two-tier check system during recipient creation: validation and verification.

Validation

Validation is the preliminary check performed immediately upon the POST /v1/accounts request. This process ensures that the submitted recipient data conforms to the required schema and regional formatting rules, such as field lengths and format checks.

If the data is malformed, the API returns an HTTP error status code and the recipient resource is not created. In such cases, you must surface the specific error details to the customer to rectify the input before re-attempting the request.

Verification

For certain supported currencies, a more in-depth verification process is carried out once the initial validation has been passed. This level of verification, called confirmation of payee (CoP), confirms details like the existence of the account or that the recipient's account number and name match the records held by the destination bank.

Supported currencies

Recipient verification is currently active for:

  • CNY (Chinese Yuan)
  • EUR (Euro, for Enterprise/Embedded payouts to SEPA accounts)
  • IDR (Indonesian Rupiah)
  • INR (Indian Rupee)
  • KRW (South Korean Won)

Verification sequence and results

All checks run sequentially during recipient creation. If an earlier step fails, later steps do not run.

Step 1: Field-level validation

  • Fails: Recipient response returns an error and recipient is not created. Fix the input and retry.
  • Passes: For currencies without verification, the recipient is created. For currencies with verification, the verification step begins.

Step 2: Verification (CoP)

This step can pass or result in either a non-blocking or blocking outcome.

  • If verification passes, the recipient is created and ready for use.
  • A non-blocking outcome means the recipient is created but may require additional action before the recipient can be used for a transfer.
  • A blocking outcome means an error occurred during the verification (either because the account doesn't exist or the bank details are not valid). In this case, the recipient is not created and you should retry the request with updated recipient details.

Review the next section, Handling verification, for details about how to proceed with both successful and non-blocking outcomes.

Handling verification

When a recipient resource is successfully created, the verification results are contained in the confirmations object of the create recipient account response. The confirmations.outcomes array provides the details about the type of verification and the status.

Verification outcomes

The outcomes.outcome field in the confirmations object for a recipient account that was successfully created indicates the status of each verification check that occurred.

Verification outcomes can be:

  • SUCCESS
  • FAILURE
  • PARTIAL_FAILURE
  • COULD_NOT_CHECK

SUCCESS indicates that verification was successful and the details are correct. The recipient resource is ready for immediate use, with no further action required.

If the outcome is anything other than successful, this indicates a non-blocking outcome and additional action may be required before you can use the recipient for a transfer.

Check the outcomes.requiresCustomerAcceptance field to determine what action is required, if any.

  • If requiresCustomerAcceptance is false: This means a minor discrepancy may exist, but the recipient is created and usable. You can choose to inform the customer of the discrepancy, but no further action is required to proceed.
  • If requiresCustomerAcceptance is true: This means the recipient cannot be used for a transfer without explicit approval from the customer. To move the recipient to a usable state, you must present the mismatch details from the outcomes array to the customer.
    • If they choose to update the details, submit the corrected data by creating a new recipient with a new POST call to the /v1/accounts endpoint.
    • If the user confirms the existing details and makes no changes, make a PATCH call to the recipient confirmation endpoint to supply the customer's explicit acceptance and unblock the account.

Currency-specific verification guides

Review our currency-specific verification guides to learn how each supported currency manages the validation and verification processes.

These guides include details about what fields get checked for each currency and supported recipient types, explain the verification outcomes possible for that currency, and provide sample payloads for success and multiple error states.