Best practices for payments

Client-side token management

When implementing the client-side authorize method, it's crucial to gather all necessary customer information beforehand. Missing details should prompt an early termination of the process, preventing the execution of the authorize method to avoid customer frustration.

The authorize method returns a promise, which will either resolve with an authorization token for order creation or reject with an error message. Proper handling of promise rejection is vital to direct customers on the next steps, ensuring a seamless user experience.

Errors encountered during interactions with Ledyer Payments will be managed within Ledyer's own dialog interface. Once the promise is fulfilled, this dialog automatically closes.

const handleProceedWithLedyer = async () => {
  try {
    const authResponse = await window.ledyer.payments.api.authorize(authArgs);

    // ... some time will pass while the user is interacting with the dialog

    if (authResponse) {
      // if status is authorized, the order is ready to be created
      if (authResponse.state === "authorized") {
        // Get the authorization token to create an order from your backend
        const authToken = authResponse.authorizationToken;
      }

      // if status is awaitingSignatory, ledyer will let you know when the order is ready
      // to be created by calling the notification, while waiting for a sign you can create
      // a draft order in your backend but make sure to mark it as pending or something similar.
      // It's not ready to be an order before a signatory has signed it.
      if (authResponse.status === "awaitingSignatory") {
        // Create a "pending order" in your backend
      }

      // redirect the user to a success page
    }
  } catch (error) {
    // Handle error
  }
};

---

Update order

Once the Ledyer payments dialog is opened we are trying to take up all screen space in order to focus the customer to complete the purchase. In some cases it might still be possible to update the order while the dialog is opened, which is why we always recommend to close the dialog after an update from backend has been made, this is done in the client by:

// close the dialog
window.ledyer.payments.api.close();

// then run the authorize method again
window.ledyer.payments.api.authorize(authArgs);

Closing the dialog will cause the user to enter a new risk and fraud assessment process.

---

Cancel unused authorizations

If an authorization token is not going to be used it can be canceled by the following request.

Example Request

curl -X DELETE \
  -H 'authorization: Bearer v4.public.eyJpc3MiOiJs...' \
  https://api.sandbox.ledyer.com/v1/authorization-tokens/:token

---

Manage an order with the status "awaitingSignatory"

Sometimes a session needs to be signed by a signatory before it can become an order. This means the session will stay as a session and only turn into an order once it's signed. In your order management system, you probably need to create an order to reserve stock, etc. In these cases, we recommend the following steps:

1. Make sure to pass an order ID from your system as a reference when creating the session. If that's not possible, you can use Ledyer's session ID instead.
2. When the session status is "awaitingSignatory," create an order in your system and mark it as pending or similar.
3. When the session is signed, you'll receive a notification from Ledyer. The reference you passed to the session will be included in the notification. Use this reference to find the order in your system and mark it as processing or similar.

---