Documentation

ERROR_BENEFICIARY_DETAILS_IN_REQUEST_AND_SAVED_BENEFICIARY_DETAILS_MISMATCH

Message: The request attempted an operation that requires a beneficiary ID, but the details in the request do not match the details in the saved beneficiary object. The request was rejected. Corrective action: Use the values that were saved in the beneficiary object or create a new beneficiary.

Explanation: You provided a beneficiary ID together with explicit details that conflict with the original saved data. Match the request body to the saved entity or omit the redundant fields.

ERROR_CREATE_BENEFICIARY

Message: The request tried to create a beneficiary for a payout, but the country was not recognized. The request was rejected. Corrective action: In the country field, use the correct 2-letter ISO 3166-1 ALPHA-2 code.

Explanation: The country provided in the beneficiary details does not exist in the system. Use a valid code such as SG or US.

Error Example: post /v1/payouts/beneficiary {"country":"UK"}

Correct Example:

post /v1/payouts/beneficiary
{
    "country": "GB",
    "entity_type": "individual"
}

ERROR_CREATE_BENEFICIARY_COUNTRY_NOT_VALID

Message: The request tried to create a beneficiary for a payout, but the country was not recognized. The request was rejected. Corrective action: Use the correct 2-letter ISO 3166-1 ALPHA-2 code, in uppercase letters, for the country field.

Explanation: The value for country is missing or incorrect. Ensure that you provide a valid 2-letter identifier.

Error Example: {"country":"UK"}

Correct Example:

{
    "country": "GB"
}

ERROR_CREATE_BENEFICIARY_CURRENCY_NOT_VALID

Message: The request tried to create a beneficiary for a payout, but the currency was missing or not recognized. The request was rejected. Corrective action: Use the correct 3-letter ISO 4217 code for the currency, in uppercase letters, for the currency field.

Explanation: You failed to provide a valid 3-letter currency identifier. Check the response to List Payout Method Types to see which currencies are supported for the target country.

Error Example: {"currency":"$"}

Correct Example:

{
    "currency": "USD"
}

ERROR_DELETE_PAYOUT_BENEFICIARY

Message: The request tried to delete a beneficiary, but the beneficiary was not found. The request was rejected. Corrective action: Use the ID of a valid beneficiary.

Explanation: You attempted to remove a beneficiary that does not exist or has already been deleted. Before you send the request, run Retrieve Beneficiary to verify the ID.

Correct Example:

delete /v1/payouts/beneficiary/beneficiary_94956e29ed5959a51afc6717787c00af

ERROR_GET_BENEFICIARY

Message: The request attempted an operation that requires a payout beneficiary, but the beneficiary was not found. The request was rejected. Corrective action: Use the ID of a valid beneficiary.

Explanation: You provided an invalid beneficiary ID in the path or body of the request. Ensure that the beneficiary exists by initially running the Retrieve Beneficiary request.

Error Example: get /v1/payouts/beneficiary/beneficiary_7723

Correct Example:

get /v1/payouts/beneficiary/beneficiary_cb009f46c8dcd85004c8054541287723

ERROR_UPDATE_BENEFICIARY_WITH_NO_NEW_FIELDS

Message: The request attempted to update a beneficiary field, but its value has already been defined. The request was rejected. Corrective action: Update only values of beneficiary fields that were not previously defined.

Explanation: You tried to modify a protected beneficiary field that cannot be changed after creation.

ERROR_VALIDATE_PAYOUT_BENEFICIARY

Message: The request tried to validate a beneficiary, but there was an error in the input fields. The request was rejected. Corrective action: Run Get Payout Required Fields.

Explanation: The validation check failed due to invalid data in the beneficiary object. Ensure that all fields are valid according to the response in Get Payout Required Fields.