跳转至

Quick start

使用Liquido Elements构建自定义支付流程

下面, 我们将学习怎么嵌入Liquido Elements的支付表单完成支付流程. 包含客户端和服务端使用Liquido Elements的代码样例，以使用各种付款方式完成付款.

支付流程概览

Liquido 使用一个PaymentOrder对象去呈现你的业务订单用于收集支付信息, 尝试支付和跟踪支付状态的变化.

支付流程如下图.

payment-flow

代码示例

package com.liquido.sample.controller.PaymentController;

import org.springframework.web.bind.annotation.RestController;
import org.springframework.web.bind.annotation.PostMapping;

import com.liquido.Liquido;
import com.liquido.model.PaymentOrder;
import com.liquido.param.PaymentOrderCreateParams;

@RestController
public class PaymentController {

    @PostMapping("/create-payment-order")
    public ResponseEntity<Object> createPaymentOrder(){
        // This is your client id, client secret and API key.
        Liquido.clientId = "6nvu4u2fnpc7ja0r8g69fjg72k";
        Liquido.clientSecret = "14ltoodv6cr40j0498t8b66d26sqqd5td245dj6isnla2fqa0vv9"
        Liquido.apiKey = "fztXT5QuK755svjly94H6anwAYD1Ap3249jH2djc"

        PaymentOrderCreateParams params = 
            PaymentOrderCreateParams.builder()
                .amount(1000)
                .currency("BRL")
                .country("BR")
                .build();
        PaymentOrder paymentOrder = PaymentOrder.create(params);

        Map<String, String> responseBody = new HashMap<>();
        responseBody.put("orderCredentials", paymentOrder.getOrderCredentials())
        retrun responseBody;
    }

}

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="utf-8" />
    <title>Accept a payment</title>
    <meta name="description" content="A demo of a payment on Liquido" />
    <meta name="viewport" content="width=device-width, initial-scale=1" />
    <link rel="stylesheet" href="checkout.css" />
    <script src="https://js.stripe.com/v3/"></script>
    <script src="checkout.js" defer></script>
  </head>
  <body>
    <!-- Display a payment form -->
    <form id="payment-form">
      <div id="payment-element">
        <!--Liquido.js injects the Payment Element-->
      </div>
      <button id="submit">
        <div class="spinner hidden" id="spinner"></div>
        <span id="button-text">Pay now</span>
      </button>
      <div id="payment-message" class="hidden"></div>
    </form>
  </body>
</html>

let elements;

initialize();
checkStatus();

document
  .querySelector("#payment-form")
  .addEventListener("submit", handleSubmit);

// 创建PaymentOrder 并获取order_credentials
async function initialize() {
  const response = await fetch("/create-payment-order", {
    method: "POST"
  });
  const { orderCredentials } = await response.json();

  const appearance = {
    theme: 'liquido',
  };
  elements = liquido.elements({ appearance, orderCredentials });

  const paymentElement = elements.create("payment");
  paymentElement.mount("#payment-element");
}

async function handleSubmit(e) {
  e.preventDefault();
  setLoading(true);

  const { error } = await liquido.confirmPayment({
    elements,
    confirmParams: {
      // 支付成功后的重定向页面
      return_url: "http://localhost:4242/checkout.html",
    },
  });

  // 只有当支付方式同步返回结果时才会有对应的异常结果, 一些第三方支付方式，比如pix，返回的是一个重定向到第三方的支付地址。
  if (error.type === "card_error" || error.type === "validation_error") {
    showMessage(error.message);
  } else {
    showMessage("An unexpected error occurred.");
  }

  setLoading(false);
}

// 查询支付状态
async function checkStatus() {
  const orderCredentials = new URLSearchParams(window.location.search).get(
    "order_credentials"
  );

  if (!orderCredentials) {
    return;
  }

  const { paymentOrder } = await liquido.retrievePaymentOrder(orderCredentials);

  switch (paymentOrder.status) {
    case "SETTLED":
      showMessage("Payment succeeded!");
      break;
    case "IN_PROGRESS":
      showMessage("Your payment is processing.");
      break;
    case "REJECTED":
      showMessage("Your payment was rejected, please try again.");
      break;
    default:
      showMessage("Something went wrong.");
      break;
  }
}

// ------- UI helpers -------

function showMessage(messageText) {
  const messageContainer = document.querySelector("#payment-message");

  messageContainer.classList.remove("hidden");
  messageContainer.textContent = messageText;

  setTimeout(function () {
    messageContainer.classList.add("hidden");
    messageText.textContent = "";
  }, 4000);
}

// Show a spinner on payment submission
function setLoading(isLoading) {
  if (isLoading) {
    // Disable the button and show a spinner
    document.querySelector("#submit").disabled = true;
    document.querySelector("#spinner").classList.remove("hidden");
    document.querySelector("#button-text").classList.add("hidden");
  } else {
    document.querySelector("#submit").disabled = false;
    document.querySelector("#spinner").classList.add("hidden");
    document.querySelector("#button-text").classList.remove("hidden");
  }
}

/* Variables */
* {
  box-sizing: border-box;
}

body {
  font-family: -apple-system, BlinkMacSystemFont, sans-serif;
  font-size: 16px;
  -webkit-font-smoothing: antialiased;
  display: flex;
  justify-content: center;
  align-content: center;
  height: 100vh;
  width: 100vw;
}

form {
  width: 30vw;
  min-width: 500px;
  align-self: center;
  box-shadow: 0px 0px 0px 0.5px rgba(50, 50, 93, 0.1),
    0px 2px 5px 0px rgba(50, 50, 93, 0.1), 0px 1px 1.5px 0px rgba(0, 0, 0, 0.07);
  border-radius: 7px;
  padding: 40px;
}

.hidden {
  display: none;
}

#payment-message {
  color: rgb(105, 115, 134);
  font-size: 16px;
  line-height: 20px;
  padding-top: 12px;
  text-align: center;
}

#payment-element {
  margin-bottom: 24px;
}

/* Buttons and links */
button {
  background: #5469d4;
  font-family: Arial, sans-serif;
  color: #ffffff;
  border-radius: 4px;
  border: 0;
  padding: 12px 16px;
  font-size: 16px;
  font-weight: 600;
  cursor: pointer;
  display: block;
  transition: all 0.2s ease;
  box-shadow: 0px 4px 5.5px 0px rgba(0, 0, 0, 0.07);
  width: 100%;
}
button:hover {
  filter: contrast(115%);
}
button:disabled {
  opacity: 0.5;
  cursor: default;
}

/* spinner/processing state, errors */
.spinner,
.spinner:before,
.spinner:after {
  border-radius: 50%;
}
.spinner {
  color: #ffffff;
  font-size: 22px;
  text-indent: -99999px;
  margin: 0px auto;
  position: relative;
  width: 20px;
  height: 20px;
  box-shadow: inset 0 0 0 2px;
  -webkit-transform: translateZ(0);
  -ms-transform: translateZ(0);
  transform: translateZ(0);
}
.spinner:before,
.spinner:after {
  position: absolute;
  content: "";
}
.spinner:before {
  width: 10.4px;
  height: 20.4px;
  background: #5469d4;
  border-radius: 20.4px 0 0 20.4px;
  top: -0.2px;
  left: -0.2px;
  -webkit-transform-origin: 10.4px 10.2px;
  transform-origin: 10.4px 10.2px;
  -webkit-animation: loading 2s infinite ease 1.5s;
  animation: loading 2s infinite ease 1.5s;
}
.spinner:after {
  width: 10.4px;
  height: 10.2px;
  background: #5469d4;
  border-radius: 0 10.2px 10.2px 0;
  top: -0.1px;
  left: 10.2px;
  -webkit-transform-origin: 0px 10.2px;
  transform-origin: 0px 10.2px;
  -webkit-animation: loading 2s infinite ease;
  animation: loading 2s infinite ease;
}

@-webkit-keyframes loading {
  0% {
    -webkit-transform: rotate(0deg);
    transform: rotate(0deg);
  }
  100% {
    -webkit-transform: rotate(360deg);
    transform: rotate(360deg);
  }
}
@keyframes loading {
  0% {
    -webkit-transform: rotate(0deg);
    transform: rotate(0deg);
  }
  100% {
    -webkit-transform: rotate(360deg);
    transform: rotate(360deg);
  }
}

@media only screen and (max-width: 600px) {
  form {
    width: 80vw;
    min-width: initial;
  }
}

构建服务端

创建支付订单

在服务端添加一个接口用于创建PaymentOrder. PaymentOrder是跟踪用户付款的生命周期付款意图跟踪客户的付款生命周期,跟踪任何失败的付款尝试,并确保只向客户收取一次费用.在响应中返回PaymentOrder的客户端凭证,以完成对客户端的付款.

构建一个收款页面

加载 Liquido.js

使用Liquido.js通过确保将付款详细信息直接发送到Liquido而不会访问您的服务器来保持PCI合规性. 始终从js.liquido.com 加载Liquido.js以保持合规性. 不要将脚本包含在包中或自己托管.

定义支付表单

在结账表单中添加一个空的占位符div. Liquido将iframe插入到该div中,以安全地收集付款信息.

获取PaymentOrder

结账页面加载后，立即向服务器发出请求以创建新的PaymentOrder. 接口返回的 orderCredentials 用于完成付款.

初始化 Liquido Elements

使用 order_credentials 初始化 Liquido Elements UI库. Elements管理收集付款详细信息所需的UI组件.

Create the PaymentElement

创建一个PaymentElement并将其安装到付款表单中的占位符<div>.这会嵌入一个带有动态表单的iframe，该表单显示可从 PaymentOrder 获得的已配置付款方式类型，从而允许您的客户选择付款方式。 该表单会自动收集所选付款方式类型的相关付款详细信息。

在客户端完成付款

处理提交事件

监听表单的提交事件以了解何时通过 Liquido API 确认付款.

完成付款

调用confirmPayment(), 传递 PaymentElement 和 return_url 以指示 Liquido 在完成付款后应将用户重定向到何处.

处理错误

如果有任何即时错误(例如，您客户的卡被拒绝)，Liquido.js会返回错误. 向您的客户显示该错误消息,以便他们可以重试.

展示付款状态

当Liquido将客户重定向到return_url时, order_credentials查询参数由Liquido.js附加到url. 使用它来检索PaymentOrder以确定向您的客户显示什么.

回到页面顶部