Payment failures

A payment can fail while Melio collects the funds from your internal account or while it delivers them to the payee. Either way the payment moves to failed, and Melio settles the money automatically. Here is what happens and how to recover.

What can fail

Collection - the debit from your internal (funding) account does not go through.
Delivery - the funds cannot be delivered to the payee, or the transfer is returned.
Risk review - the payment is declined before any money moves. See Payment lifecycle.

How Melio handles it

Failure	What Melio does	The money
Collection fails	Payment moves to `failed`.	Nothing was collected, so there is nothing to refund.
Delivery fails or is returned	Payment moves to `failed`.	Melio automatically refunds the amount to the original internal account. Fees already charged are not refunded.
Declined in risk review	Payment moves to `failed`.	No money moved, so there is nothing to refund.

Melio does not automatically retry a failed payment. To try again, create a new payment.

The `failureReason` object

A payment with status: "failed" carries a failureReason object explaining why. It is absent on every other status.

{
  "id": "pay_9f8c7b6a5d4e3f21",
  "status": "failed",
  "failureReason": {
    "type": "failed-to-collect",
    "code": "R01_INSUFFICIENT_FUNDS",
    "message": "The account had insufficient funds to cover the payment."
  }
}

Field	Description
`type`	Which leg of the payment failed. One of three values, listed below. Branch on this first.
`code`	The specific reason, named after the industry code behind it. Branch on this for precise handling.
`message`	A human-readable explanation. Display-only - the wording may change at any time, so never match on it.

Failure types

This set is fixed - every failure is one of these three.

`type`	What it means	The money
`failed-to-collect`	The funds could not be debited from the originating account.	Never left the payer.
`failed-to-deliver`	The funds were collected but could not be credited to the receiving account.	Returned to the payer.
`risk-declined`	The payment was declined in review before processing began.	Never moved.

Failure codes

Codes are named after the industry code that produced them, so a code can be matched against a bank return without a translation table:

R##_* - a NACHA ACH return code.
CARD_* - an ISO 8583 card issuer decline.

Everything else is a Melio-level outcome with no industry code behind it.

Always read code together with type. The same ACH return can arrive on either leg, so R02_ACCOUNT_CLOSED means your account under failed-to-collect and the payee’s account under failed-to-deliver.

ACH return codes

Can appear under failed-to-collect or failed-to-deliver.

`code`	Meaning
`R01_INSUFFICIENT_FUNDS`	The account had insufficient funds to cover the payment.
`R02_ACCOUNT_CLOSED`	The account is closed.
`R03_NO_ACCOUNT`	The account could not be located at the bank.
`R04_INVALID_ACCOUNT_NUMBER`	The account number is invalid.
`R05_UNAUTHORIZED_DEBIT`	The debit was not authorized for this consumer account.
`R08_PAYMENT_STOPPED`	A stop payment was placed on the transfer.
`R09_UNCOLLECTED_FUNDS`	The account balance was not yet collected and available.
`R10_NOT_AUTHORIZED`	The account holder advised that the transfer was not authorized.
`R13_INVALID_ROUTING_NUMBER`	The routing number is invalid.
`R16_ACCOUNT_FROZEN`	The account is frozen.
`R20_NON_TRANSACTION_ACCOUNT`	The account does not permit transfers of this kind.
`R23_CREDIT_REFUSED`	The receiving bank refused the credit.
`R29_CORPORATE_NOT_AUTHORIZED`	The business advised that the corporate debit was not authorized.
`R84_CREDIT_EXCEPTION`	The transfer completed with a credit exception.

Card decline codes

Appear under failed-to-collect only, since only the payer funds a payment with a card.

`code`	Meaning
`CARD_DO_NOT_HONOR`	The card issuer declined the charge.
`CARD_INVALID_TRANSACTION`	The card issuer rejected the transaction as invalid.
`CARD_INSUFFICIENT_FUNDS`	The card had insufficient funds to cover the payment.
`CARD_LIMIT_EXCEEDED`	The payment exceeds the withdrawal limit on the card.
`CARD_BALANCE_UNAVAILABLE`	The card balance was not available.

Delivery outcomes

Appear under failed-to-deliver only. These have no industry code behind them.

`code`	Meaning
`CHECK_RETURNED`	The check was returned.
`VIRTUAL_CARD_EXPIRED`	The virtual card expired before the recipient used it.
`CANCELED_BY_RECIPIENT`	The recipient canceled the payment.
`RECIPIENT_DETAILS_NOT_PROVIDED`	The recipient did not provide their payment details in time.

Risk decline codes

Appear under risk-declined only.

`code`	Meaning
`VERIFICATION_FAILED`	The payment could not be verified.
`UNSUPPORTED_BUSINESS_TYPE`	Payments involving this type of business are not supported.
`UNSUPPORTED_LOCATION`	Payments involving this location are not supported.
`PAYMENT_NOT_ALLOWED`	This payment is not allowed.
`DUPLICATE_PAYMENT_DETECTED`	The payment was declined as a duplicate of another payment.
`RISK_DECLINED`	The payment was declined in risk review.

A decline is reported as the bare RISK_DECLINED whenever the underlying reason cannot be disclosed. It does not mean the reason is unknown, and you should not infer anything from it beyond the payment having been declined.

Generic codes

Each type has one generic code, reported when the specific reason is unavailable or cannot be disclosed. These are the codes to fall back to when you receive one you do not recognize.

`type`	Generic `code`	Meaning
`failed-to-collect`	`COLLECTION_FAILED`	The funds could not be collected from the originating account.
`failed-to-deliver`	`DELIVERY_FAILED`	The payment could not be delivered to the receiving account.
`risk-declined`	`RISK_DECLINED`	The payment was declined in risk review.

RISK_DECLINED is listed under Risk decline codes as well. It is the only code that serves both roles: a reason in its own right and the generic for its type. The two are indistinguishable by design, so never treat its presence as meaning the reason was unavailable.

Handling codes safely

New code values are added over time as payment rails and review rules change. To stay forward-compatible:

Branch on type first. The three types are fixed and cover every failure.
Then branch on the code values you care about.
Treat an unrecognized code as the generic code for its type - COLLECTION_FAILED, DELIVERY_FAILED or RISK_DECLINED - rather than as an error.
Never parse message. Show it to a user if useful, but do not match on it.

How you find out

Melio sends api.payment.updated; fetch the payment to see it is now failed and read its failureReason.

GET /payments/pay_9f8c7b6a5d4e3f21

The business is also emailed about the failure. For a delivery failure the email confirms the funds are being refunded and the expected timing. If you would rather handle these notifications yourself, ask Melio to configure which failure emails are sent.

How to recover

There is no retry on the same payment; recovery is always a new POST /payments. What to fix first depends on the type:

`type`	Typical fix
`failed-to-collect`	Resolve the funding account - add funds, or correct the bank or card details - then create the payment again.
`failed-to-deliver`	Get corrected delivery details from the payee, add a new receiving account, and create the payment against it.
`risk-declined`	Review the code. Some declines are resolvable (for example by supplying missing verification); others are final. Contact Melio if it is unclear.

POST /payments

Test failures in the sandbox

Drive a payment to failed in a non-production environment with the simulation endpoint, so you can build and verify your handling before going live. It is available in non-production only and returns 404 in production.

POST /simulations/payments/pay_9f8c7b6a5d4e3f21/actions

{
  "action": "fail-deliver"
}

Use fail-collect for a collection failure, fail-deliver for a delivery failure, and risk-decline for a risk decline. action is the only required field; an optional metadata object is echoed to logs and not persisted on the payment. No other fields are accepted - the request is rejected with 400 VALIDATION_ERROR if you send one.

The simulation controls which type you get, not which code. Use it to verify that your handling reacts correctly to each type and to an unrecognized code; it is not a way to reproduce a specific ACH return.

Related: an undeposited check is automatically voided after 90 days, and the payment is refunded like any other delivery failure. It is reported as CHECK_RETURNED.

Get started

Core resources

Building with the API

Risk, compliance & going live

Tools

Legal

What can fail

How Melio handles it

The `failureReason` object

Failure types

Failure codes

ACH return codes

Card decline codes

Delivery outcomes

Risk decline codes

Generic codes

Handling codes safely

How you find out

How to recover

Test failures in the sandbox

What can fail

How Melio handles it

The failureReason object

Failure types

Failure codes

ACH return codes

Card decline codes

Delivery outcomes

Risk decline codes

Generic codes

Handling codes safely

How you find out

How to recover

Test failures in the sandbox

The `failureReason` object