集成 seQura 支付

2026-06-10 05:43

seQura 是西班牙领先的先买后付服务提供商之一，提供根据当地偏好量身定制的免息计划和长期融资。它专注于电子商务集成和风险驱动的承保，深受 Z 世代和千禧一代的信赖。seQura 已被 15 个行业的 5,000 多家商户接受。

本文为您介绍如何在您的网站或应用中接入 seQura。无论买家使用移动设备还是桌面浏览器，均可通过简洁的集成流程，快速获得安全、高效的本地化支付能力，显著提升买家的支付体验与成功率。

支付流程

seQura 的支付流程由以下集成步骤组成：

sequra payment flow.png

买家进入结账页面。
创建支付请求。
买家选择支付方式并提交订单后，商户服务端调用 pay（单笔支付）接口以发起支付请求。
处理支付推进链接。
商户客户端跳转至支付请求返回的 URL 页面，或唤起相关应用程序完成支付。
获取支付结果。
商户服务端接收 Antom 服务端返回的支付结果通知，并根据结果进行相应的业务处理。通过以下两种方法之一获取支付结果：

异步通知：在 pay（单笔支付）接口中设置 paymentNotifyUrl 字段，以指定接收异步通知的地址。当支付成功或过期时， Antom 会使用 notifyPayment 接口向您发送异步通知。
主动查询：调用 inquiryPayment 接口来查询支付状态。

集成准备

在您开始集成前，请阅读集成指南及接口概述文档，了解服务端接口的集成步骤及调用接口的注意事项，并确保已完成以下预配置：

已获得 client ID。
已完成密钥配置。
已完成异步通知接收地址的配置。
集成服务端 SDK 资源包，并完成接口库安装及请求示例初始化。具体操作请参阅服务端 SDK。

集成步骤

请按照以下步骤开始集成：

在支付方式列表添加 seQura
创建支付订单
获取跳转支付推进链接
接收异步通知

步骤 1：在支付方式列表添加 seQura 客户端

按照步骤 1：添加支付方式列表的操作，获取并在买家订单页面的支付方式列表中展示 seQura 的标识和名称。

步骤 2：创建支付请求服务端

调用 pay（单笔支付）接口来创建支付请求。以下列出的关键参数是向 seQura 发起支付请求所必需的，并会根据商户的业务性质进行相应调整。

注意：
您的业务性质在渠道注册时确定，分为三种类型：产品类（product），服务类（service）或者旅行类（lodging 或 flight）。如需了解更多信息，请联系业务团队（BD）。
对于业务性质涉及住宿（lodging）或航班（flight）的商户，seQura 对相关产品（如酒店、航班、租车等）有特定限制。如不符合这些要求，将导致支付失败。
单程旅行：仅允许出发地和目的地均位于欧洲经济区（EEA）内，且最短预订时间需提前至少 14 天。
往返旅行：可面向全球，最短预订时间同样需提前至少 14 天。

参数名称	是否必需	描述
env.terminalType	是	商户服务适用的终端类型。有效值为： `WEB`: 客户端终端类型为网站，通过 PC 浏览器打开。 `WAP`: 客户端终端类型为 H5 页面，通过移动浏览器打开。 `APP`: 客户端终端类型为移动应用。 `MINI_APP`: 商户端的终端类型为手机小程序。
env.osType	否	操作系统类型。有效值包括： `IOS`: 表示操作系统是苹果的 iOS。 `ANDROID`: 表示操作系统是谷歌的 Android。注意：当 terminalType 不是 `WEB` 时，请指定此字段。
productCode	是	表示正在使用的支付产品，这是在合同中规定的。对于单笔支付，值设置为 `CASHIER_PAYMENT`。
paymentRequestId	是	商户为标识支付请求所分配的专属 ID。
settlementStrategy	是	支付请求的结算策略。
paymentAmount.currency	是	商家在订单币种中请求接收的支付金额币种。
paymentAmount.value	是	商家在订单币种中请求接收的支付金额。
paymentExpiryTime	否	支付有效期是一个特定时间，超过这个时间后，支付将失效，收单机构或商户必须终止订单处理。
paymentRedirectUrl	是	买家完成支付后跳转到的商户页面链接。
paymentNotifyUrl	否	用于接收结果通知的链接。
paymentMethod.paymentMethodType	是	支付方式选项中包含的支付方式类型。在此集成场景中,，此参数的值为 `SEQURA`。
paymentMethod.paymentMethodMetaData.channelOptionBill.channelPromotionCode	否	一个或多个由商户与 seQura 约定的促销码，用于标识促销活动，例如免息分期。多个促销码之间必须使用逗号分隔。最多支持 99 个促销码，且每个促销码长度不得超过 20 个字符。Antom 对该参数近作透传，不进行校验。注意：当商户与 seQura 约定了促销活动编码时，该参数必填。
order.orderAmount	是	直接向客户提供服务或商品的商户的订单金额。此字段用于用户消费记录显示或支付结果页面。
order.referenceOrderId	是	在商户端标识订单的专属 ID，由直接向客户提供服务或商品的商户分配。
order.orderDescription	是	订单的摘要描述。此字段用于显示用户消费记录以及其他后续操作。
order.buyer.buyerEmail	否	买家的电子邮件地址。注意：此参数在 seQura 支付场景中是必需的。
order.buyer.buyerName.firstName	是	买家的名字。
order.buyer.buyerName.lastName	是	买家的姓。
order.goods.goodsCategory	否	商品类别。该数值由渠道注册过程中定义的业务性质决定。在 seQura 支付场景中，有效值为以下之一： `product` `service` `flight` `lodging` 注意: 此参数在 seQura 支付场景中是必需的。
order.goods.referenceGoodsId	是	标识商品的专属 ID。
order.goods.goodsName	是	商品或服务名称。
order.goods.goodsQuantity	否	商品数量称。注意: 此参数在 seQura 支付场景中是必需的。
order.goods.goodsUnitAmount.currency	是	商品价格的币种代码。
order.goods.goodsUnitAmount.value	是	商品价格金额。
order.goods.goodsDiscountAmount.currency	是	商品折扣或促销金额的币种。
order.goods.goodsDiscountAmount.value	是	商品折扣或促销的金额。
order.goods.deliveryMethodType	否	商品的配送方式。有效值为： `PHYSICAL`: 表示配送方式为实物交付。 `DIGITAL`: 表示配送方式为虚拟商品交付。注意：此参数在 seQura 支付场景中是必需的。
order.goods.goodsEndsOnTime	否	服务类产品的最晚截止日期，如在线课程、美容套餐、牙科套餐等。值遵循 ISO 8601 标准格式。例如，“2019-11-27T12:01:01+08:00”。注意：在 seQura 支付场景下，当参数 order.goods.goodsCategory 的值为 `service` 时，请指定此参数。
order.transit.legs.departureTime	否	此次行程的出发时间。值遵循 ISO 8601 标准格式。例如，“2019-11-27T12:01:01+08:00”。注意：在 seQura 支付场景下，当参数 order.goods.goodsCategory 的值为 `flight` 时，请指定此参数。
order.transit.legs.arrivalTime	否	此次行程的到达时间。值遵循 ISO 8601 标准格式。例如，“2019-11-27T12:01:01+08:00”。注意：在 seQura 支付场景下，当参数 order.goods.goodsCategory 的值为 `flight` 时，请指定此参数。
order.transit.legs.carrierNo	否	行程承运商的 IATA 代码，可从官方航空公司指南（OAG）或其等效文件中获取处获取。注意：在 seQura 支付场景下，当参数 order.goods.goodsCategory 的值为 `flight` 时，请指定此参数。
order.transit.legs.departureAirportCode	否	航班出发地点的 IATA 机场代码。注意：在 seQura 支付场景下，当参数 order.goods.goodsCategory 的值为 `flight` 时，请指定此参数。
order.transit.legs.arrivalAirportCode	否	航班目的地的 IATA 机场代码。注意：在 seQura 支付场景下，当参数 order.goods.goodsCategory 的值为 `flight` 时，请指定此参数。
order.transit.passengers.passengerName.firstName	否	行程乘客的名字。注意：在 seQura 支付场景下，当参数 order.goods.goodsCategory 的值为 `flight` 时，请指定此参数。
order.transit.passengers.passengerName.lastName	否	行程乘客的姓。注意：在 seQura 支付场景下，当参数 order.goods.goodsCategory 的值为 `flight` 时，请指定此参数。
order.transit.passengers.passengerId	否	商户为标识乘客所分配的专属 ID。注意：此参数必须以 SHA-256 格式进行编码。在 seQura 支付场景下，当参数 order.goods.goodsCategory 的值为 `flight` 时，请指定此参数。
order.lodging.checkInDate	否	入住日期。在未出现或预订的情况下，则为计划到达日期。值遵循 ISO 8601 标准格式。例如，“2019-11-27T12:01:01+08:00”。注意：在 seQura 支付场景下，当参数 order.goods.goodsCategory 的值为 `lodging` 时，请指定此参数。
order.lodging.checkOutDate	否	客人退房的日期。值遵循 ISO 8601 标准格式。例如，“2019-11-27T12:01:01+08:00”。注意：在 seQura 支付场景下，当参数 order.goods.goodsCategory 的值为 `lodging` 时，请指定此参数。
order.lodging.hotelName	否	酒店名称。注意：在 seQura 支付场景下，当参数 order.goods.goodsCategory 的值为 `lodging` 时，请指定此参数。
order.lodging.hotelAddress.city	否	酒店所在的城市、区、郊区、城镇或村庄名称。注意：在 seQura 支付场景下，当参数 order.goods.goodsCategory 的值为 `lodging` 时，请指定此参数。
order.lodging.hotelAddress.region	否	酒店的二位字母的国家或地区代码。更多信息，请参阅 ISO 3166 国家代码标准。注意：在 seQura 支付场景下，当参数 order.goods.goodsCategory 的值为 `lodging` 时，请指定此参数。
order.shipping	否	配送信息。注意：在 seQura 支付场景下，当参数 order.goods.deliveryMethodType 的值为 `PHYSICAL` 时，请指定此参数。
order.shipping.shippingName.firstName	是	收件人名字。
order.shipping.shippingName.lastName	是	收件人的姓。
order.shipping.shippingAddress	否	收货地址。注意：在 seQura 支付场景下，当参数 order.goods.deliveryMethodType 的值为 `PHYSICAL` 时，请指定此参数。
order.shipping.shippingCarrier	否	实体产品的配送服务供应商。注意：在 seQura 支付场景下，当参数 order.goods.deliveryMethodType 的值为 `PHYSICAL` 时，请指定此参数。
order.shipping.shippingPhoneNo	否	收件人电话号码。注意：在 seQura 支付场景下，当参数 order.goods.deliveryMethodType 的值为 `PHYSICAL` 时，请指定此参数。
order.shipping.shiptoEmail	否	虚拟商品的发送电子邮件。注意：在 seQura 支付场景下，当参数 order.goods.deliveryMethodType 的值为 `PHYSICAL` 时，请指定此参数。

有关更完整参数的参数信息，请参考 pay（单笔支付）接口。

以下示例代码展示了如何调用 pay（单笔支付）接口：

copy
public static void payByBNPL() {
    AlipayPayRequest alipayPayRequest = new AlipayPayRequest();
    alipayPayRequest.setProductCode(ProductCodeType.CASHIER_PAYMENT);

    // 替换为您的 paymentRequestId
    String paymentRequestId = UUID.randomUUID().toString();
    alipayPayRequest.setPaymentRequestId(paymentRequestId);

    // 设置金额
    Amount amount = Amount.builder().currency("EUR").value("4200").build();
    alipayPayRequest.setPaymentAmount(amount);

    // 设置支付方式
    PaymentMethod paymentMethod = PaymentMethod.builder().paymentMethodType("SEQURA").build();
    alipayPayRequest.setPaymentMethod(paymentMethod);

    // 替换为您的 orderId
    String orderId = UUID.randomUUID().toString();

    // 设置买家信息
    Buyer buyer = Buyer.builder().referenceBuyerId("yourBuyerId").build();

    // 设置订单信息
    Order order = Order.builder().referenceOrderId(orderId)
    .orderDescription("antom testing order").orderAmount(amount).buyer(buyer).build();
    alipayPayRequest.setOrder(order);

    // 设置环境信息
    Env env = Env.builder().terminalType(TerminalType.WEB).clientIp("1.2.3.4").build();
    alipayPayRequest.setEnv(env);

    // 替换为您的通知地址
    alipayPayRequest.setPaymentNotifyUrl("https://www.yourNotifyUrl.com");

    // 替换为您的跳转地址
    alipayPayRequest.setPaymentRedirectUrl("https://www.yourMerchantWeb.com");

    // 支付
    AlipayPayResponse alipayPayResponse = null;
    try {
        alipayPayResponse = CLIENT.execute(alipayPayRequest);
    } catch (AlipayApiException e) {
        String errorMsg = e.getMessage();
        // 处理错误信息
    }
}

以下代码展示了一个请求报文的示例：

copy
{
    "paymentNotifyUrl": "http://www.yourRedirect.com/notify",
    "paymentRedirectUrl": "http://www.yourRedirect.com",
    "paymentRequestId": "202601292222250740iGSA",
    "paymentExpiryTime": "2027-01-29T01:45:52+0000",
    "env": {
        "terminalType": "WEB"
    },
    "paymentAmount": {
        "currency": "EUR",
        "value": "2900"
    },
    "settlementStrategy": {
        "settlementCurrency": "USD"
    },
    "productCode": "CASHIER_PAYMENT",
    "paymentMethod": {
        "paymentMethodType": "SEQURA"
    },
    "order": {
        "lodging": {
            "checkInDate": "2026-01-29T16:26:46+08:00",
            "checkOutDate": "2026-01-30T16:26:46+08:00",
            "hotelName": "Hotel Chaplin",
            "hotelAddress": {
                "region": "ES",
                "city": "Madrid"
            }
        },
        "orderAmount": {
            "currency": "EUR",
            "value": "2900"
        },
        "referenceOrderId": "2026012974670334435214",
        "shipping": {
            "shippingName": {
                "firstName": "**",
                "lastName": "Kyle",
                "fullName": "K***i"
            },
            "shippingCarrier": "DHL",
            "shippingPhoneNo": "600222866",
            "shipToEmail": "int***@sequra.es",
            "shippingAddress": {
                "zipCode": "08002",
                "address1": "************************",
                "address2": "",
                "city": "Barcelona",
                "state": "Spain",
                "region": "ES"
            }
        },
        "goods": [
            {
                "referenceGoodsId": "2026012962249154292481",
                "goodsUrl": "qinghailipipeng",
                "goodsCategory": "lodging",
                "goodsUnitAmount": {
                    "currency": "EUR",
                    "value": "2900"
                },
                "goodsQuantity": "1",
                "goodsName": "boom",
                "goodsSkuName": "boom boom room",
                "goodsBrand": "antom boom"
            }
        ],
        "orderDescription": "ANTOM_ZZ",
        "buyer": {
            "referenceBuyerId": "Kyle Li70106299633166",
            "buyerEmail": "int***@sequra.es",
            "buyerName": {
                "firstName": "******",
                "lastName": "Pelo Apelo",
                "fullName": "P***s"
            }
        }
    }
}

以下代码展示了一个响应报文的示例：

copy
{
    "normalUrl": "https://ac.alipay.com/page/sandbox/unified-checkout.html?payRequestId=20260416890313000037B6745405099&pspName=SEQURA",
    "paymentAmount": {
        "currency": "EUR",
        "value": "2900"
    },
    "paymentCreateTime": "2026-04-16T00:41:38-07:00",
    "paymentId": "202604161940108001001887B0291011918",
    "paymentRequestId": "PAYMENT_20260416154137445_AUTO",
    "result": {
        "resultCode": "PAYMENT_IN_PROCESS",
        "resultMessage": "payment in process",
        "resultStatus": "U"
    }
}

下表展示了响应报文中 result.resultStatus 字段可能返回的值，请您根据指引进行处理：

*result.resultStatus*	信息	后续操作
`S`	支付成功。	跳转至 normalUrl 继续推进支付。
`F`	支付失败。	请关闭当前交易或更换 paymentRequestId 重新下单。
`U`	未知原因。	如果返回了 `PAYMENT_IN_PROCESS` 结果码，那就跳转至 normalUrl 跳转至 seQura 支付中间页。如果返回了其他结果码，您可关闭当前交易或更换 paymentRequestId 重新下单。

注意：如果您未收到响应报文，可能是网络超时所致。您可关闭当前交易或更换 paymentRequestId 重新下单。

常见问题

问：响应中的哪个 URL 应该被使用？
答：Antom只会返回 normalUrl。商户服务器需要将此 URL 传递给商户前端用于页面跳转。

问：为什么 API 响应中没有返回 normalUrl？
答：请确保根据业务性质在 API 请求中正确传递所有必需参数。

问：terminalType 参数应该如何设置？
答：
WEB：客户端终端类型为网站，通过 PC 浏览器打开。
WAP：客户端终端类型为 H5 页面，通过移动浏览器打开。（这指的是买家从商户的移动浏览器页面发起交易的情况，而不是商户期望获得的 H5 页面。）
APP：客户端终端类型为移动应用程序。

步骤 3：获取跳转支付推进链接客户端

商户服务端获得 Antom 返回的支付推进链接后，按照步骤 3：获取跳转支付推进链接的操作将该地址传递给前端，并由商户前端跳转至 seQura 支付页面。

下图展示 seQura 支付页面的效果：

常见问题
问：对于 paymentRedirectUrl 参数有什么特殊处理要求吗？
答：默认设置为 HTTPS 地址，URL 中的特殊字符不能进行编码，否则支付流程将出现异常。

问：回跳至商户结果页面是否代表支付成功？
答：不能仅凭回跳至商户页面来判断支付是否成功，可能存在以下情况导致回跳商户页失败：
买家支付成功后，可能因网络等原因导致未能回跳至商户页面。
当买家未完成支付时，也可能通过支付方式端的入口回跳至商户页面。
Antom 不会在 paymentRedirectUrl 拼接表示支付结果的字段信息。

步骤 4：接收异步通知服务端

按照支付结果异步通知的操作设置接收支付结果通知的地址并处理相应结果。

支付后操作

完成支付后，您可对交易进行以下支付后的操作：

查询交易服务端

除了通过异步通知功能获取买家支付结果外，您还可以主动调用查询服务获取相应结果。您可以调用 inquiyPayment API，通过 paymentRequestId 查询支付状态。请按照查询交易部分详细说明的步骤进行操作。

取消交易服务端

seQura 支付方式不支持取消交易操作。请使用退款功能返还已支付的金额。

退款服务端

若您需要了解 Antom 的退款规则及如何对成功的交易发起退款，请参阅退款。

对账服务端

交易完成后，使用 Antom 提供的财务报告进行对账。有关如何对账和 Antom 结算规则的更多信息，请参阅对账。

集成 seQura 支付

支付流程

集成准备

集成步骤

步骤 1：在支付方式列表添加 seQura 客户端

步骤 2：创建支付请求 服务端

步骤 3：获取跳转支付推进链接 客户端

步骤 4：接收异步通知 服务端

支付后操作

查询交易 服务端

取消交易 服务端

退款 服务端

对账 服务端