> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mnai.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Simulating failed payments

> Force a payment link payment to fail in Sandbox, and see every webhook each failure sends.

> [!WARNING]
>
> This works in Sandbox only, and it is for testing. In production, a payment link for one of these amounts is an ordinary payment.

In Sandbox, the test bank accepts any buyer account, so a payment link payment normally succeeds. To test a failure, create a payment link for one of the trigger amounts below. When the buyer pays it, Meridian forces the matching outcome.

To receive the webhooks, ask Meridian to register an endpoint for each payment link transaction event. See [Track payments](https://docs.mnai.com/products/realtime-collections/tracking-payments-with-webhooks.md#before-you-start).

## Trigger amounts

The trigger is the amount you set on the link, `creditAmount`, in the link's currency. A link for ₱14.14 fails the debit whatever the exchange rate and fees are. Any other amount behaves as normal.

| Link amount | What Meridian simulates | Final `status` | `statusReason` |
| :- | :- | :- | :- |
| `12.12` | The risk check declines the payment | `FAILED` | `Simulated risk decline` |
| `13.13` | The risk check returns an error | `FAILED` | `Simulated risk error` |
| `14.14` | The debit of the buyer's bank account fails | `FAILED` | `Transaction failed while debiting funds` |
| `15.15` | The debit of the buyer's bank account times out | `FAILED` | `Transaction timed out while debiting funds` |

## Run a test

**1. Create a session**

Call [Create a Session](https://docs.mnai.com/products/realtime-collections/api-reference/sessions/create-session.md) with your operator details, as you do for any payment link.

**2. Create a link with a trigger amount**

Call [Create a Payment Link](https://docs.mnai.com/products/realtime-collections/api-reference/payment-links/create-payment-link.md) and set `creditAmount` to the trigger amount. This link fails the debit:

```json theme={null}
{
  "recurrenceType": "SINGLE",
  "referenceId": "TEST-FAILED-PAYMENT",
  "referenceLabel": "Failed debit test",
  "creditAmount": "14.14",
  "debitCurrency": "USD",
  "creditCurrency": "PHP",
  "endDate": "2027-01-31",
  "sessionKey": "ussandbox-b1x2k0dzsbpc4cz8c8xrvfel"
}
```

Include any custom fields your merchant requires. Without them, the call returns `400`.

**3. Pay the link as the buyer**

Open the payment link, connect a Sandbox test bank account, and authorize the payment. See [Collect a payment](https://docs.mnai.com/products/realtime-collections/sending-a-buyer-to-pay.md) for how to send a buyer to the link.

**4. Receive the webhooks**

Meridian sends the webhooks listed for that amount under [Webhooks for each amount](#webhooks-for-each-amount). Check that your system handles each one, and that your buyer sees your failure page.

## Webhooks for each amount

Each tab lists the webhooks in the order Meridian sends them, then the body of each one. Every webhook carries `X-Meridian-Resource-Type: payment_link_transaction`, and the event name in `X-Meridian-Event-Type`.

IDs, timestamps, and USD amounts in these examples are samples. `paymentLink` is shortened here, and the real webhook carries the full payment link.

> [tab] 12.12 Risk declined
>
> Meridian's risk check declines the payment before any debit. The transaction goes straight from `PENDING` to `FAILED`.
>
> | # | Event | `status` | `previousStatus` | `statusReason` |
> | :- | :- | :- | :- | :- |
> | 1 | `payment_link_transaction_created` | `PENDING` | `null` | `null` |
> | 2 | `payment_link_transaction_failed` | `FAILED` | `PENDING` | `Simulated risk decline` |
>
> > [!NOTE]
> >
> > The link cannot be paid again after this failure. Create a new link to repeat the test.
>
> > [accordion] 1. payment\_link\_transaction\_created (PENDING)
> >
> > ```json theme={null}
> > {
> >   "paymentLink": {
> >     "id": "usmer-n1hpx2d89pdpnmpdjlorb995",
> >     "referenceId": "TEST-FAILED-PAYMENT",
> >     "creditAmount": "12.12",
> >     "creditCurrency": "PHP",
> >     "...": "..."
> >   },
> >   "transaction": {
> >     "id": "uspay-echo1fuz76usacpgicexz5vb",
> >     "createdAt": "2026-11-13T09:05:00.000Z",
> >     "updatedAt": "2026-11-13T09:05:00.000Z",
> >     "completedAt": null,
> >     "status": "PENDING",
> >     "previousStatus": null,
> >     "statusReason": null,
> >     "debitAmount": "0.23",
> >     "debitCurrency": "USD",
> >     "creditAmount": "12.12",
> >     "creditCurrency": "PHP",
> >     "fee": "0.00"
> >   }
> > }
> > ```
>
> > [accordion] 2. payment\_link\_transaction\_failed (FAILED)
> >
> > ```json theme={null}
> > {
> >   "paymentLink": {
> >     "id": "usmer-n1hpx2d89pdpnmpdjlorb995",
> >     "referenceId": "TEST-FAILED-PAYMENT",
> >     "creditAmount": "12.12",
> >     "creditCurrency": "PHP",
> >     "...": "..."
> >   },
> >   "transaction": {
> >     "id": "uspay-echo1fuz76usacpgicexz5vb",
> >     "createdAt": "2026-11-13T09:05:00.000Z",
> >     "updatedAt": "2026-11-13T09:05:02.000Z",
> >     "completedAt": null,
> >     "status": "FAILED",
> >     "previousStatus": "PENDING",
> >     "statusReason": "Simulated risk decline",
> >     "debitAmount": "0.23",
> >     "debitCurrency": "USD",
> >     "creditAmount": "12.12",
> >     "creditCurrency": "PHP",
> >     "fee": "0.00"
> >   }
> > }
> > ```

> [tab] 13.13 Risk error
>
> Meridian's risk check returns an error before any debit. The transaction goes straight from `PENDING` to `FAILED`.
>
> | # | Event | `status` | `previousStatus` | `statusReason` |
> | :- | :- | :- | :- | :- |
> | 1 | `payment_link_transaction_created` | `PENDING` | `null` | `null` |
> | 2 | `payment_link_transaction_failed` | `FAILED` | `PENDING` | `Simulated risk error` |
>
> > [!NOTE]
> >
> > The link cannot be paid again after this failure. Create a new link to repeat the test.
>
> > [accordion] 1. payment\_link\_transaction\_created (PENDING)
> >
> > ```json theme={null}
> > {
> >   "paymentLink": {
> >     "id": "usmer-n1hpx2d89pdpnmpdjlorb995",
> >     "referenceId": "TEST-FAILED-PAYMENT",
> >     "creditAmount": "13.13",
> >     "creditCurrency": "PHP",
> >     "...": "..."
> >   },
> >   "transaction": {
> >     "id": "uspay-echo1fuz76usacpgicexz5vb",
> >     "createdAt": "2026-11-13T09:05:00.000Z",
> >     "updatedAt": "2026-11-13T09:05:00.000Z",
> >     "completedAt": null,
> >     "status": "PENDING",
> >     "previousStatus": null,
> >     "statusReason": null,
> >     "debitAmount": "0.24",
> >     "debitCurrency": "USD",
> >     "creditAmount": "13.13",
> >     "creditCurrency": "PHP",
> >     "fee": "0.00"
> >   }
> > }
> > ```
>
> > [accordion] 2. payment\_link\_transaction\_failed (FAILED)
> >
> > ```json theme={null}
> > {
> >   "paymentLink": {
> >     "id": "usmer-n1hpx2d89pdpnmpdjlorb995",
> >     "referenceId": "TEST-FAILED-PAYMENT",
> >     "creditAmount": "13.13",
> >     "creditCurrency": "PHP",
> >     "...": "..."
> >   },
> >   "transaction": {
> >     "id": "uspay-echo1fuz76usacpgicexz5vb",
> >     "createdAt": "2026-11-13T09:05:00.000Z",
> >     "updatedAt": "2026-11-13T09:05:02.000Z",
> >     "completedAt": null,
> >     "status": "FAILED",
> >     "previousStatus": "PENDING",
> >     "statusReason": "Simulated risk error",
> >     "debitAmount": "0.24",
> >     "debitCurrency": "USD",
> >     "creditAmount": "13.13",
> >     "creditCurrency": "PHP",
> >     "fee": "0.00"
> >   }
> > }
> > ```

> [tab] 14.14 Debit failed
>
> The risk check passes, then the debit of the buyer's bank account fails.
>
> | # | Event | `status` | `previousStatus` | `statusReason` |
> | :- | :- | :- | :- | :- |
> | 1 | `payment_link_transaction_created` | `PENDING` | `null` | `null` |
> | 2 | `payment_link_transaction_status_updated` | `PROCESSING` | `PENDING` | `null` |
> | 3 | `payment_link_transaction_failed` | `FAILED` | `PROCESSING` | `Transaction failed while debiting funds` |
>
> > [!NOTE]
> >
> > The link stays payable after a failed debit, so the buyer can pay it again. Every attempt fails the same way and sends these three webhooks again, each time for a new transaction. Use this to test repeated failures on one link.
>
> > [accordion] 1. payment\_link\_transaction\_created (PENDING)
> >
> > ```json theme={null}
> > {
> >   "paymentLink": {
> >     "id": "usmer-n1hpx2d89pdpnmpdjlorb995",
> >     "referenceId": "TEST-FAILED-PAYMENT",
> >     "creditAmount": "14.14",
> >     "creditCurrency": "PHP",
> >     "...": "..."
> >   },
> >   "transaction": {
> >     "id": "uspay-echo1fuz76usacpgicexz5vb",
> >     "createdAt": "2026-11-13T09:05:00.000Z",
> >     "updatedAt": "2026-11-13T09:05:00.000Z",
> >     "completedAt": null,
> >     "status": "PENDING",
> >     "previousStatus": null,
> >     "statusReason": null,
> >     "debitAmount": "0.26",
> >     "debitCurrency": "USD",
> >     "creditAmount": "14.14",
> >     "creditCurrency": "PHP",
> >     "fee": "0.00"
> >   }
> > }
> > ```
>
> > [accordion] 2. payment\_link\_transaction\_status\_updated (PROCESSING)
> >
> > ```json theme={null}
> > {
> >   "paymentLink": {
> >     "id": "usmer-n1hpx2d89pdpnmpdjlorb995",
> >     "referenceId": "TEST-FAILED-PAYMENT",
> >     "creditAmount": "14.14",
> >     "creditCurrency": "PHP",
> >     "...": "..."
> >   },
> >   "transaction": {
> >     "id": "uspay-echo1fuz76usacpgicexz5vb",
> >     "createdAt": "2026-11-13T09:05:00.000Z",
> >     "updatedAt": "2026-11-13T09:05:02.000Z",
> >     "completedAt": null,
> >     "status": "PROCESSING",
> >     "previousStatus": "PENDING",
> >     "statusReason": null,
> >     "debitAmount": "0.26",
> >     "debitCurrency": "USD",
> >     "creditAmount": "14.14",
> >     "creditCurrency": "PHP",
> >     "fee": "0.00"
> >   }
> > }
> > ```
>
> > [accordion] 3. payment\_link\_transaction\_failed (FAILED)
> >
> > ```json theme={null}
> > {
> >   "paymentLink": {
> >     "id": "usmer-n1hpx2d89pdpnmpdjlorb995",
> >     "referenceId": "TEST-FAILED-PAYMENT",
> >     "creditAmount": "14.14",
> >     "creditCurrency": "PHP",
> >     "...": "..."
> >   },
> >   "transaction": {
> >     "id": "uspay-echo1fuz76usacpgicexz5vb",
> >     "createdAt": "2026-11-13T09:05:00.000Z",
> >     "updatedAt": "2026-11-13T09:05:04.000Z",
> >     "completedAt": null,
> >     "status": "FAILED",
> >     "previousStatus": "PROCESSING",
> >     "statusReason": "Transaction failed while debiting funds",
> >     "debitAmount": "0.26",
> >     "debitCurrency": "USD",
> >     "creditAmount": "14.14",
> >     "creditCurrency": "PHP",
> >     "fee": "0.00"
> >   }
> > }
> > ```

> [tab] 15.15 Debit timeout
>
> The risk check passes, then the debit of the buyer's bank account times out. The transaction waits in `TIMED_OUT_REVERSAL_DECISION_PENDING` before it fails.
>
> | # | Event | `status` | `previousStatus` | `statusReason` |
> | :- | :- | :- | :- | :- |
> | 1 | `payment_link_transaction_created` | `PENDING` | `null` | `null` |
> | 2 | `payment_link_transaction_status_updated` | `PROCESSING` | `PENDING` | `null` |
> | 3 | `payment_link_transaction_status_updated` | `TIMED_OUT_REVERSAL_DECISION_PENDING` | `PROCESSING` | `null` |
> | 4 | `payment_link_transaction_failed` | `FAILED` | `TIMED_OUT_REVERSAL_DECISION_PENDING` | `Transaction timed out while debiting funds` |
>
> > [!NOTE]
> >
> > The link cannot be paid again after this failure. Create a new link to repeat the test.
>
> > [accordion] 1. payment\_link\_transaction\_created (PENDING)
> >
> > ```json theme={null}
> > {
> >   "paymentLink": {
> >     "id": "usmer-n1hpx2d89pdpnmpdjlorb995",
> >     "referenceId": "TEST-FAILED-PAYMENT",
> >     "creditAmount": "15.15",
> >     "creditCurrency": "PHP",
> >     "...": "..."
> >   },
> >   "transaction": {
> >     "id": "uspay-echo1fuz76usacpgicexz5vb",
> >     "createdAt": "2026-11-13T09:05:00.000Z",
> >     "updatedAt": "2026-11-13T09:05:00.000Z",
> >     "completedAt": null,
> >     "status": "PENDING",
> >     "previousStatus": null,
> >     "statusReason": null,
> >     "debitAmount": "0.28",
> >     "debitCurrency": "USD",
> >     "creditAmount": "15.15",
> >     "creditCurrency": "PHP",
> >     "fee": "0.00"
> >   }
> > }
> > ```
>
> > [accordion] 2. payment\_link\_transaction\_status\_updated (PROCESSING)
> >
> > ```json theme={null}
> > {
> >   "paymentLink": {
> >     "id": "usmer-n1hpx2d89pdpnmpdjlorb995",
> >     "referenceId": "TEST-FAILED-PAYMENT",
> >     "creditAmount": "15.15",
> >     "creditCurrency": "PHP",
> >     "...": "..."
> >   },
> >   "transaction": {
> >     "id": "uspay-echo1fuz76usacpgicexz5vb",
> >     "createdAt": "2026-11-13T09:05:00.000Z",
> >     "updatedAt": "2026-11-13T09:05:02.000Z",
> >     "completedAt": null,
> >     "status": "PROCESSING",
> >     "previousStatus": "PENDING",
> >     "statusReason": null,
> >     "debitAmount": "0.28",
> >     "debitCurrency": "USD",
> >     "creditAmount": "15.15",
> >     "creditCurrency": "PHP",
> >     "fee": "0.00"
> >   }
> > }
> > ```
>
> > [accordion] 3. payment\_link\_transaction\_status\_updated (TIMED\_OUT\_REVERSAL\_DECISION\_PENDING)
> >
> > ```json theme={null}
> > {
> >   "paymentLink": {
> >     "id": "usmer-n1hpx2d89pdpnmpdjlorb995",
> >     "referenceId": "TEST-FAILED-PAYMENT",
> >     "creditAmount": "15.15",
> >     "creditCurrency": "PHP",
> >     "...": "..."
> >   },
> >   "transaction": {
> >     "id": "uspay-echo1fuz76usacpgicexz5vb",
> >     "createdAt": "2026-11-13T09:05:00.000Z",
> >     "updatedAt": "2026-11-13T09:05:04.000Z",
> >     "completedAt": null,
> >     "status": "TIMED_OUT_REVERSAL_DECISION_PENDING",
> >     "previousStatus": "PROCESSING",
> >     "statusReason": null,
> >     "debitAmount": "0.28",
> >     "debitCurrency": "USD",
> >     "creditAmount": "15.15",
> >     "creditCurrency": "PHP",
> >     "fee": "0.00"
> >   }
> > }
> > ```
>
> > [accordion] 4. payment\_link\_transaction\_failed (FAILED)
> >
> > ```json theme={null}
> > {
> >   "paymentLink": {
> >     "id": "usmer-n1hpx2d89pdpnmpdjlorb995",
> >     "referenceId": "TEST-FAILED-PAYMENT",
> >     "creditAmount": "15.15",
> >     "creditCurrency": "PHP",
> >     "...": "..."
> >   },
> >   "transaction": {
> >     "id": "uspay-echo1fuz76usacpgicexz5vb",
> >     "createdAt": "2026-11-13T09:05:00.000Z",
> >     "updatedAt": "2026-11-13T09:05:08.000Z",
> >     "completedAt": null,
> >     "status": "FAILED",
> >     "previousStatus": "TIMED_OUT_REVERSAL_DECISION_PENDING",
> >     "statusReason": "Transaction timed out while debiting funds",
> >     "debitAmount": "0.28",
> >     "debitCurrency": "USD",
> >     "creditAmount": "15.15",
> >     "creditCurrency": "PHP",
> >     "fee": "0.00"
> >   }
> > }
> > ```

`statusReason` is plain text, so do not match on its exact wording. Use `transaction.status` to decide what happened. See [Track payments](https://docs.mnai.com/products/realtime-collections/tracking-payments-with-webhooks.md) for how to handle these webhooks.

The payment link's own status can also change after a failed payment. Read it with [Get a Payment Link](https://docs.mnai.com/products/realtime-collections/api-reference/payment-links/get-payment-link.md).
