Offsite Transactions
A transaction may require the end-user to interact with a 3rd party service. Common examples would be 3D secure (for payment card authentication and liability shift) and PayPal or other similar wallets.
Initiate Transaction
Nothing changes about the transaction initiation. It would be initiated exactly as we did in our tutorial.
Transaction Response
Unknown due to network errors
If the result of the transaction is unknown, it means we
must investigate the status. If the status is timeout or
connection-error then we should wait for the notification
to be pinged with an updated result. The end-user can be
handled in different ways:
- Presented with a loading screen, while waiting for the ping.
- Presented with a message that the transaction is being verified. And then confirming once completed via email.
- Some combination of the two... such as waiting for 1 minute, followed by a message stating that the transaction is being verified and they would receive a confirmation once completed.
Unknown due to Required Offsite Interaction
If the status is waiting-approval, then the user must be
directed to the approvalUrl which is found in the _links
section of the API response.
The approval url can typically be opened by either pop or iframe that is 400 x 800 pixels in size. Pop is more popular and a better UX on mobile devices. Because of the vast growth and popularity of mobile, we recommend the pop.
After the user is redirected to the approval url, three things may happen:
- They may complete it and be approved.
- They may interact and not be authorized or approved.
- They may abandon (eg, close their browser or turn off their device).
After either of the first two cases, the notification url will be posted to, to alert of a change in the transaction state. You would do a get request to retrieve and confirm the transaction result.
In the event of the abandon, Rebilly cleans up old transactions
according to the schedule configured within each gateway account.
You can control that setting; however, it defaults to 1 hour.
After 1 hour, the transaction would be updated to an abandoned
result and the post to the notification url will be sent.
Importance of the Offsite Flow
Integrating the offsite flow is critical, as offsite transactions will be mandatory for many payment cards in Europe.
Tutorial for an Offsite Transaction
Prepare a new customer for offsite demo
We'll make a payment token, like we did before, but use a different card which will "simulate" a 3-D Secure authentication process.
We'll use the card number: 4000000000000101.
Then, we'll use that token when we upsert a customer, Isaac Newton.
Then, we'll upsert the order, as we did before.
Now, we're ready to demo the offsite transaction.
Before you continue
- Have you created a customer with the default card number
4000000000000101? - Do you have the customerId, recentInvoiceId, and recent invoice amount ready?
- Set up a hookbin.com webhook receiver for the demo. Do you have that hookbin endpoint ready?
Initiate the Offsite Transaction
The hookbin endpoint I generated for the demo was: https://hookb.in/nPqZlrdq7eUz0zGKdDB7
Send the request, and notice the response has a result that is unknown, a
status that is waiting-approval, and an approvalUrl in the _links section.
Wait for the Redirect and Webhook
When the user is redirected back to you, check for the corresponding transaction's result (or invoice's status). If the invoice is paid, then you can redirect the user to the "Thank you" page, or next page in your sales process.