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.

If your integration already supports Strong Customer Authentication (SCA), refer to this sub-page.

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 (redirectUrl) 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/authorize 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 redirectUrl:

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

When the outcome is Pending, redirect the customer to the URL (redirectUrl) 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:

GET /api/v3/orders/{orderNumber}

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

Deployment Update

We have made an update to the authentication flow to harmonize field naming and improve consistency across responses.

• The new redirectURL field was replaced by the existing secureLoginURL field. To ensure compatibility, the old field will continue to be included in responses, but will be deprecated.

Testing & Debugging

To simulate a redirect flow, the below parameters are necessary in the request:

"merchantUrl": "https://www.example.com",
"hostedCheckout": {},

In addition, refer to our SCA test data varying by country scope.

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.