Redirects

Together with the integration of the payment functionalities, MoneyHash recommends you set up a notification system to track all operations related to your business. This way, you can stay up to date with all operations related to each transaction. You can accomplish this using Webhooks and Redirects. This page focuses on the Redirects solution.

What are Redirects

After integrating with MoneyHash, you may want to bring your customers back to your application when certain events occur during a payment, such as a successful transaction. Redirects enable MoneyHash to automatically direct your customers to a designated web page based on the outcome of the payment, carrying the outcome details as parameters appended to your redirect URL.

Redirects are a great way to ensure a smooth user experience and keep your customers informed about the status of a transaction. The first step is to create different URLs for each possible scenario during the payment process, such as success, failure, and pending. Your customers will be directed to the appropriate page based on the outcome.

Webhooks vs Redirects

Redirects and Webhooks serve different purposes, and a reliable integration uses both together.

Redirects are a customer-facing mechanism. They return the customer's browser to your page after a payment and are ideal for updating the user interface, such as showing a success or failure screen. Because a redirect happens in the browser, it is not guaranteed. If the customer closes the tab, loses connection, or navigates away before being redirected, you will not receive it.

Webhooks are a backend mechanism. MoneyHash sends them directly to your server, independently of the customer's browser, which makes them the reliable source of truth for the final state of a payment. See the Webhooks page for more.

Do not rely on redirects to confirm payment

Because redirects happen in the customer's browser, they can be lost or manipulated. Always confirm the final payment state on your backend using Webhooks or the Get Intent API before fulfilling an order.

Setting up Redirects

Using redirects is very similar to the use of webhooks in MoneyHash. When creating a new intent to start a payment process, you provide the different redirect URLs for each possible outcome as top-level fields in the intent creation payload. The table below presents the possible parameters you can provide when creating the intent and their descriptions.

Parameter	Description
`successful_redirect_url`	The URL where customers will be redirected after a successful transaction. This page should confirm the successful completion of a transaction and may provide additional details or instructions.
`failed_redirect_url`	The URL to which customers will be redirected if a transaction fails. This page should communicate the failure, suggest possible solutions, and ensure transparency in the transaction process.
`pending_external_action_redirect_url`	The URL to redirect customers to when an action external to your application is required to complete a transaction. This page should guide users on what external action is needed and how to proceed.
`time_expired_redirect_url`	The URL to which customers will be redirected if the intent expires. This page should communicate the end of the intent, suggest possible solutions, and ensure transparency in the transaction process.
`closed_redirect_url`	The URL to which customers will be redirected if the intent is closed. This page should communicate the end of the intent, suggest possible solutions, and ensure transparency in the transaction process.

Sample Intent Creation with Redirect URLs

{
  "amount": 50.00,
  "amount_currency": "USD",
  "operation": "purchase",
  "webhook_url": "https://your-domain.com/webhook",
  "successful_redirect_url": "https://your-domain.com/success",
  "failed_redirect_url": "https://your-domain.com/failed",
  "pending_external_action_redirect_url": "https://your-domain.com/pending",
  "time_expired_redirect_url": "https://your-domain.com/expired",
  "closed_redirect_url": "https://your-domain.com/closed"
}

Redirect URL parameters

When MoneyHash redirects your customer, it appends parameters to your redirect URL describing the outcome. Your page can read these from the URL query string.

There are two kinds of redirect, and the parameters you receive depend on which one occurred:

Transaction-outcome redirects happen when a transaction was attempted and reached an outcome, such as success or failure. These carry transaction-level parameters like type, status, and transaction_id.
Intent-lifecycle redirects happen when the intent itself ends without a successful transaction, such as when it is closed or expires. These carry the intent_status parameter.

Because of this, not every parameter appears on every redirect. The table below describes each parameter and when it is present.

Below is an example of a redirect URL for a successful transaction:

https://your-domain.com/success?type=transaction.successful&status=SUCCESSFUL&transaction_id=bd915617-aa44-4523-b449-afc76a02c4b0&intent_id=LWWA7GL&amount=50.00&currency=USD&mh_data=eyJzdGF0dXMiOiAiU1VDQ0VTU0ZVTCJ9&response_code=6000&response_message=Successful

Parameter	Description
`intent_id`	The ID of the payment intent. Always present.
`amount`	The intent amount. Always present.
`currency`	The intent currency. Always present.
`mh_data`	A MoneyHash parameter carrying the redirect status. Always present. See below for details.
`type`	The transaction outcome, for example `transaction.successful`, `transaction.failed`, or `transaction.pending`. Present when a transaction was attempted.
`status`	The transaction status, for example `SUCCESSFUL`, `FAILED`, or `PENDING`. Present when a transaction was attempted.
`transaction_id`	The ID of the transaction. Present when a transaction was attempted.
`response_code`	The MoneyHash status code for the outcome, for example `6000` for success. Present when a transaction was attempted. See the Status Codes page.
`response_message`	A human-readable message describing the outcome. Present when a transaction was attempted.
`intent_status`	The final state of the intent, included when the redirect is caused by the intent being closed or expiring, for example `CLOSED` or `TIME_EXPIRED`. It is not included on successful redirects, where the outcome is carried by the transaction parameters instead.
`customer_id`	The ID of the customer associated with the payment. Present when the payment is associated with a customer.
`customer_phone_number`	The phone number of the customer associated with the payment. Present when the payment is associated with a customer.

About mh_data

mh_data is a MoneyHash parameter that contains a base64-encoded JSON object carrying MoneyHash's redirect status, for example a decoded value of status SUCCESSFUL. Decode it to read the status from a MoneyHash-owned parameter. Use mh_data only for frontend handling and customer messaging. Like all redirect parameters, it must not be used as proof of payment. Confirm the final result through Webhooks or the Get Intent API.

Redirect Strategy

The Redirect strategy feature provides control over the redirection behavior of embedded content or provider windows. With the redirect_inside_embed option, you can choose whether redirections occur within the iframe itself or open in a new popup window, ensuring a smooth and uninterrupted user journey. Conversely, opting for redirect_entire_window directs the provider redirections to take over the entire page, offering a different approach to managing user navigation. This flexibility empowers you to tailor the redirection experience according to your specific needs and preferences.

Provider dependent

While this feature enables control over redirection behavior, its implementation depends on the provider and may vary in effectiveness depending on the provider used.