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:
-
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.
-
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.
-
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:
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.
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.
Do you find this page helpful?