Transfer Reason Codes

Status reasons

If a transfer fails, Orum will send a transfer_updated webhook. The transfer object in the payload will have a status of "failed" and a status_reasons array that explains why the transfer failed. status_reasons will contain a source and/or destination item, depending on where the transfer failure occurred.

status_reasons consist of:

Field	Description
`reason_code`	A word-based code created by Orum to describe the reason for the failure. Orum reason codes are rail-agnostic.
`reason_code_message`	A human-readable description of the reason code.
`network_reason_code`	The reason code sent by the network (ex: R01).
`network_reason_code_message`	The message sent by the network.
`network_reason_code_rail_type`	The payment rail used in the transfer. Either RTP or ACH.

The network_reason_code and network_reason_message fields are populated with what Deliver receives from the network. That network information is mapped to an Orum-created reason_code and reason_code_message, which give a higher-level and more human-readable explanation of the transfer failure.

Example Webhook Payload

{
    "event_id": "cl0e13b9-7311-440b-828a-a5c13c4e342p",
    "event_type": "transfer_updated",
    "created_at": "2022-08-26T18:57:18.087Z",
    "event_data": {
        "transfer": {
            "id": "542dbbe3-cf18-4d94-a490-7dde26f5b5bp",
            "transfer_reference_id": "970d9av1-3m96",
            "amount": 200,
            "currency": "USD",
            "speed": "same_day",
            "source": {
                "account_reference_id": "3c0699pw4-2e4091",
                "customer_reference_id": "9rs61-917dna80"
            },
            "destination": {
                "account_reference_id": "p7db1-2n38ywn",
                "customer_reference_id": "5jd29a-ja2qof612"
            },
            "status": "failed",
            "status_reasons": [
                {
                    "destination": {
                        "reason_code": "unexpected_error",
                        "reason_code_message": "There was an unexpected error with this transfer request",
                        "network_reason_code": "IN03",
                        "network_reason_code_message": "The payment could not be processed at this time due to an unexpected error, please try again later.",
                        "network_reason_code_rail_type": "RTP"
                    },
                    "source": {
                        "reason_code": "insufficient_funds",
                        "reason_code_message": "There was not enough money available to complete the transfer request",
                        "network_reason_code": "AM04",
                        "network_reason_code_message": "R01 INSUFFICENT FUNDS",
                        "network_reason_code_rail_type": "ACH"
                    }
                }
            ]
        }
    }
}

Reason Codes

reason_code	reason_code_message
blocked_account	An account in the transfer request was blocked or prohibits posting of transfers against it
canceled_transfer	A transfer cancellation request was successful
closed_account	Account number specified has been closed on the bank of account's books
debit_blocked	The account owner has placed a stop payment on their account
deceased_party	One of the parties in the transfer request was deceased
duplicated_transfer	Duplicate of a previous transfer request
enterprise_insufficient_funds	There is an insufficient enterprise balance and the transfer request cannot be completed
insufficient_funds	There was not enough money available to complete the transfer request
invalid_account	The account number provided is invalid or does not exist
invalid_amount	The amount provided in the transfer request was invalid or missing
invalid_country_code	The country code utilized was invalid
invalid_currency	The currency provided in the transfer request was invalid or missing
invalid_field	There was erroneous, invalid, or missing data in the transfer request
invalid_routing	The routing number provided is invalid or does not exist
regulatory_error	The transfer could not be completed because of limitations imposed by a regulator
transfer_on_hold	Transfer request was questionable or part of anomalous activity
unauthorized_transfer	A party in the transfer request was either unknown or did not authorize this request
unavailable_financial_institution	Sending or receiving financial institution is currently not available or does not support this request type
unexpected_error	There was an unexpected error with this transfer request
unsupported_transfer	Transfer type is not supported or forbidden
wire_returned	The wire was returned from the receiving bank because it was unable to be delivered to the desired destination

Unlike the reason codes above, NOCs can exist on a transfer of anystatus(i.e. it does not have to be "failed"). The status_reasons array will still explain why the NOC occurred.status_reasons will contain a source and/or destination item, depending on where the NOC occurred.

reason_code	reason_code_message
`notification_of_change_1`	Incorrect bank account number
`notification_of_change_2`	Incorrect routing number
`notification_of_change_3`	Incorrect transit/routing number and bank account number
`notification_of_change_4`	Bank account name change
`notification_of_change_5`	Incorrect payment code
`notification_of_change_6`	Incorrect bank account number and transit code
`notification_of_change_7`	Incorrect transit/routing number, bank account number and payment code