Try Again Feature

The Try Again feature lets users retry a failed On-Ramp payment attempt directly inside the widget, without starting over. This is especially useful when the initial payment fails due to insufficient funds, card blocking, or bank rejection.

To enable and configure Try Again, contact your integration manager and specify your preferences for amount modification, payment method modification, callback behavior, and maximum retry attempts.

Configuration Options

Transaction Amount Modification

• Enabled: users can change the fiat/crypto amount during a retry.
• Disabled: original amount is preserved for all retry attempts.

Payment Method Modification

• Enabled: users can switch payment methods between attempts (e.g., from card to Google Pay).
• Disabled: users must retry with the original payment method.

Callback Configuration

• Enabled (intermediate callbacks sent): all status transitions trigger callbacks.
• Disabled (final callbacks only): only final statuses (paid, cancelled, order_failed) trigger callbacks.

Maximum Retry Attempts

Set the maximum number of times the user can retry.

Callback Behavior with Try Again

When a user retries, Mercuryo creates a new transaction with a new id. The merchant_transaction_id stays the same across all retries, allowing you to group attempts by your own transaction ID.

Parameters that may change across retries:

Callback Example — First Attempt

{
  "eventId": "ead92193-5310-4962-9730-d7280d623410",
  "data": {
    "amount": "0.00048148",
    "fiat_amount": "25.00",
    "fiat_amount_usd": "28.43",
    "id": "0c9be256a0eed7062",
    "created_at": "2024-09-11 09:48:51",
    "created_at_ts": 1726048131,
    "updated_at": "2024-09-11 09:48:53",
    "updated_at_ts": 1726048133,
    "type": "buy",
    "merchant_transaction_id": "trx_20240911_102155662",
    "currency": "BTC",
    "network": "BITCOIN",
    "fiat_currency": "EUR",
    "payment_method": "card",
    "status": "order_scheduled",
    "user": {
      "uuid4": "00e0043f-9c9a-4a93-b4b3-f10729af6ef6",
      "country_code": "de",
      "phone": "*****",
      "email": "*****"
    },
    "card": { "number": "*****" },
    "fee": "0.28",
    "partner_fee": "0.00",
    "rate": "51341.70",
    "card_masked_pan": null,
    "contract_address": null
  }
}

Callback Example — Second Attempt (Retry)

{
  "eventId": "b7c4e201-8f93-47d1-a056-e3291b804f78",
  "data": {
    "amount": "0.00024148",
    "fiat_amount": "13.7",
    "fiat_amount_usd": "13.70",
    "id": "0c9be512a0ebd8012",
    "created_at": "2024-09-11 09:50:03",
    "created_at_ts": 1726056363,
    "updated_at": "2024-09-11 09:50:53",
    "updated_at_ts": 1726056363,
    "type": "buy",
    "merchant_transaction_id": "trx_20240911_102155662",
    "currency": "BTC",
    "network": "BITCOIN",
    "fiat_currency": "USD",
    "payment_method": "mobile_pay",
    "status": "paid",
    "user": {
      "uuid4": "00e0043f-9c9a-4a93-b4b3-f10729af6ef6",
      "country_code": "de",
      "phone": "*****",
      "email": "*****"
    },
    "fee": "0.15",
    "partner_fee": "0.00",
    "rate": "56341.70",
    "card_masked_pan": null,
    "contract_address": null
  }
}

Callback Optimization Options

Disable All Intermediate Callbacks

When enabled, Mercuryo only sends callbacks for final statuses: paid, cancelled, order_failed. Intermediate statuses (new, pending) are suppressed for all transactions.

Recommended when: users can create many transactions in rapid succession and you only care about the outcome.

Without this setting, a sequence of retries will generate callbacks like:

new → pending → new → pending → new → pending → {final_status}

Disable Intermediate Callbacks for Retry Attempts Only

Intermediate callbacks are sent only for the first attempt. For all subsequent retries, only final status callbacks are sent.