Last updated 2 years ago

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:

  1. Presented with a loading screen, while waiting for the ping.
  2. Presented with a message that the transaction is being verified. And then confirming once completed via email.
  3. 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:

  1. They may complete it and be approved.
  2. They may interact and not be authorized or approved.
  3. 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 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:

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.