Accepting a one-off payment

For one-off payments you can get started by creating a new checkout using the Create a new checkout API.

A checkout session is valid for as long as you specify on the expiresAt property and you can use the Get Checkout API to check on the validity of the session including the status of the payment.

We also recommend subscribing to the checkout-status-changed webhook so you can get real-time updates on changes to the checkout session.

Buyer UI/UX

See below for the UX options that can be presented to the buyer in order to complete a checkout session

Portal Buyer UI

Once you create a checkout session you can send the buyer the URL from the checkout's link.checkoutproperty. This URL will allow the buyer to complete the payment on their computer including a mobile device.

Embeddable URL

On the checkout session's link.embeddableproperty there is an alternate version of the URL that can be loaded into an iframe in case you want to provide the checkout experience on your own website or platform.

Handling Events

When using the Portal Buyer UI

You can optionally specify the redirectLinks parameter when creating a new checkout. This way the portal can redirect to successRedirectUrl when a payment has processed successfully or to failureRedirectUrl when the payment has failed.

Please note: After a payment has been completed (either success or failure), reopening the link, will result in a immediate redirect to the links specified.

For a failed payment, you will also receive a reason query string with one of the error reasons detailed below.

There is also an expiredRedirectUrl that can be redirected if an expired checkout link is clicked.

All of these parameters are optional. If they are not included then the checkout screen will not redirect and instead will just show the default success/error/expired message.

When using the Embeddable URL

The iframe will fire one of the following events: PL_APP_CHECKOUT_SUCCESS, PL_APP_CHECKOUT_FAILED or PL_APP_CHECKOUT_EXPIRED

Note that PL_APP_CHECKOUT_FAILED will also have a reason variable.

You can listen to the iframe events and have your UI make a decision - such as hiding the iframe or displaying your own message, etc. This is solely up to you and the buyer experience you prefer to have.

Example code:

function handleCheckoutStatusEvent(e) {
  const { data } = e;

  if (data.id === "PL_APP_CHECKOUT_FAILED") {
    console.log("Checkout failed, reason:", data.reason);
    document.getElementById("theIframe").style.display = 'none';
  }
}

window.addEventListener("message", handleCheckoutStatusEvent);

Reason Codes

• MISSING_INSTRUMENT: The checkout failed because the payment instrument used (Credit/Debit Card, Bank Account, Google Pay, Apple Pay, etc.) is no longer available. In this case a new checkout needs to be created.
• INVALID_INSTRUMENT: The checkout failed because the payment instrument used (Credit/Debit Card, Bank Account, Google Pay, Apple Pay, etc.) didn't pass all the validations. A new checkout needs to be created and the buyer needs to be advised to check all of their info entered also matches their card or bank information, including the address their bank has on file for them.
• CHARGE_INSTRUMENT_ERROR: The payment instrument was not authorized. A new checkout needs to be created and the buyer needs to be instructed to contact their bank if they authorization rejection is an error.
• APPLICATION_ERROR: There was a internal application error. Our team is automatically notified, but a new checkout is needed to try again. These are rare.

Payment Methods

Currently, the buyer UI will allow the buyer to complete the checkout as a guest by just typing in their card or banking information. They can also log in to save payment information for future reuse or select previously saved payment information. This works for both portal or embeddable formats described above.