Migration Guide: Supporting Redirects

Introduction

To fulfill compliance requirements but also reduce maintenance effort for you as a merchant, we now support an asynchronous redirect flow. As an existing merchant, you need to adjust your integration to handle this new flow while maintaining compatibility with the synchronous process.

This guide walks you through the required changes step by step.

Changes Required

To support the redirect flow, ensure your integration covers the following updates:

1. Include a Return URL in the Authorize Request

   • Add a merchantUrl parameter to your regular authorization request. This is where customers will be redirected after completing their action.
   • If you already have SCA in place, you only need to add the merchantURL parameter to your authorization request to have the redirect flow automatically enabled.

2. Handle 'Pending' as a New Outcome

   • Your system should recognize Pending as a valid response status.
   • When a transaction is Pending, redirect the customer to the URL (secureLoginUrl) provided in the response.

3. Verify the Transaction Status After Customer Returns

   • Once the customer is redirected back to your platform, verify the transaction status.
   • Ensure you handle success, failure, or pending scenarios appropriately.

Step-by-Step Implementation

Step 1: Update the Authorize Request

Modify your POST /api/v3/authorization request to include a merchantUrl parameter:

{
  "customer": {
    "firstName": "John",
    "lastName": "Doe"
  },
  ...
  "merchantUrl": "https://yourwebsite.com/redirect-handler"
}

Step 2: Handle 'Pending' as a New Outcome

Your system should be able to handle a response containing the outcome Pending and extract the secureLoginUrl:

{
  "outcome": "Pending",
  "secureLoginUrl": "https://secure-dev.riverty.dev/..."
}

When the outcome is Pending, redirect the customer to the URL (secureLoginUrl) provided in the response.

Step 3: Capture the Redirect and Verify Status

Once the customer completes the action, they will be sent back to your merchantUrl. Upon return, you need to verify that the status has changed to a final status:

Option 1: GET the order status

The standard approach is to call our GET Order endpoint and request the status of the order. orderDetails.status should have changed to Accepted or Rejected. If a customer has cancelled the flow, it could also be in the status Cancelled or Expired.

GET /api/v3/orders/{orderNumber}

Example response:

{
  "orderDetails": {
      "status": "Accepted",
      ...
  }
  ...
}

Handle the response accordingly.

Further details can be found in the API specifications.

Option 2: Interpret the status appended to the Return URL

An alternative option of handling the redirect feedback which does not require a server-to-server verification is to check the status which got appended to the merchantUrl.

Following parameters get appended to the URL: &ordernumber=DE521720703119315&orderstatus=accepted&signature=86cf82800...a95932d9335ee3cb

The signature is a HMAC hashed string consisting of {ordernumber}.{orderstatus}.

Using this approach you do not add latency to the checkout and could immediately show the outcome to the shopper.

Option 3: Use Webhooks to receive the final status of the redirect flow

Merchants can utilize webhooks to receive real-time updates when customers reach a final status in the redirect flow. This allows them to efficiently process orders and guide customers through the next steps seamlessly. Integrating webhooks enhances the user experience by automating workflows based on the latest transaction status.
For further details on using webhooks, refer to our Webhooks documentation.

Testing & Debugging

To simulate a redirect flow, use following placeholder for the billing customer: First Name: Risky - Last Name: OTP

Redirects within Apps

To support robust redirect flows within apps which works with all the different local authentication schemes we recommend to either initiate the redirect in the native browser or use SFSafariViewController.

Next Steps

• Ensure your system can handle redirects seamlessly.
• Test the implementation using the provided placeholder.
• Deploy the updated flow while keeping synchronous handling intact.

For further details, refer to our main Redirect documentation.