Skip to main content

Restoring a Payment Intent

In some cases, users might not complete their payment before the Payment Intent expires, perhaps due to not confirming the payment in time, losing the confirmation, or abandoning the checkout flow. If you were to simply ask the user to try again, this would create a new Payment Intent, which can result in many abandoned or duplicate transactions in your records.

To simplify recovery and reduce unnecessary abandoned transactions, Modem Pay allows you to restore an existing Payment Intent (if it was not already completed or fully charged). This lets you reinstate or recharge on the same Payment Intent, rather than forcing the creation of a new one. This is especially useful for "retry" or "resume" payment flows in your application.

Note: Payment Intents can only be restored within 12 hours of their original creation time. Attempting to restore after this window will not succeed.

Restore Payment Intent Endpoint​

PATCH /payments/restore/:intent-id

  • :intent-id is the ID of the Payment Intent you want to restore.
  • Only Payment Intents that are not completed and were created within the last 12 hours are eligible for restoration.

Example cURL Request​

curl -X PATCH "https://api.modempay.com/h2h/v1/payments/restore/YOUR_PAYMENT_INTENT_ID" \
  -H "Authorization: Bearer YOUR_API_KEY"

Example Response​

// assuming original charge was afrimoney
{
  "message": "Please authorize the payment",
  "transactionId": "XNNCIKVCR",
  "next_step": {
    "requiresAuthorization": true,
    "auth_mode": "confirm",
    "auth_length": 0,
    "openExternal": false,
    "launch_url": ""
  },
  "confirmation_steps": "....",
  "payment_intent_id": "eb4e0386-0325-449b-8207-271fe7db4880"
}

After restoration, a webhook event named payment_intent.restored will be sent to your callback_url or configured webhook endpoint, so your backend can update its records or notify the user.

Checking the Payment Intent Status​

If you want to manually verify the state of a Payment Intent before attempting a restore (for example, to check if it was already completed or is still available), you can retrieve its current status using the following endpoint:

GET /payments/:intent-id

curl -X GET "https://api.modempay.com/h2h/v1/payments/YOUR_PAYMENT_INTENT_ID" \
  -H "Authorization: Bearer YOUR_API_KEY"

Example Response​

{
  "id": "f201d23a-2ab7-452b-b71c-41b6a7ea764f",
  "status": "expired",
  "amount": 2500,
  "currency": "GMD"
  // ...other payment intent fields
}

Notes​

  • Restoring a Payment Intent allows for a seamless retry experience and helps prevent unnecessary abandoned transactions in your dashboard.
  • Only Payment Intents with a status of "expired", "initialize", or "requires_payment_method" that were created in the last 12 hours can be restored.
  • Once restored, the user can resume payment and complete the transaction without starting over.
  • You will receive a webhook notification (payment_intent.restored) upon successful restoration.
  • Always check the Payment Intent status via the provided GET endpoint if you need real-time verification or want to build a custom retry flow.