跳转至

回调消息

当用户在payment link完成支付，liquido会根据商户创建payment link时的callbackUrl进行通知。 支付完成后，如果商户发起退款，退款成功后也会通知商户。

请求

POST {callbackUrl}

Headers
{
    "Liquido-Signature": "algorithm=HmacSHA256,timestamp={{timestamp_in_seconds}},signature={{signature}}"
}
Body Content-Type: application/json
{
    "eventType": "CHARGE_SUCCEEDED",
    "data":  {
        "linkId": "egGFE9mdsSa6DM5YwNGY5w",
        "orderId": "2022-12-15T14:07:00-01",
        "amount": 9999,
        "currency": "BRL",
        "country": "BR",
        "paymentStatus": "SETTLED",
        "redirectUrl": "https://your-domain/redirect",
        "callbackUrl": "https://your-domain/callback/",
        "finalPaymentMethod": "CREDIT_CARD",
        "finalStatusTimestamp": 1671098127,
        "finalStatusTime": "2022-12-15 17:55:27",
        "refundAmount": null,
        "refundStatus": "INITIAL_STATUS",
        "refundTime": null,
        "refundTimestamp": 0,
        "name": "buyer name",
        "email": "liquido-test@gmail.com",
        "phone": "+5511999999999",
        "documentId": "51234567890",
        "description": null,
        "allowPaymentMethods": [
            "PIX",
            "BOLETO",
            "BANK_TRANSFER_BR",
            "CREDIT_CARD"
        ],
        "billingAddress": {
            "zipCode": "04849333",
            "state": "SP",
            "city": "sao paulo",
            "district": "Jardim Gaivotas",
            "street": "Rua 9 de setembro",
            "number": "15",
            "country": "BR",
            "complement": "casa"
        },
        "refunded": false,
        "shippingAddress": {
          "name": "name",
          "countryCode": "BR",
          "province": "province/state",
          "city": "city",
          "postalCode": "04849334",
          "line1": "Address Info",
          "line2": "Address Info"
        },
        "refunded": false,
        "expiredTime": "2023-10-18 09:21:06",
        "createTime": "2023-10-11 09:21:06",
        "updateTime": "2023-10-11 09:21:06",
        "needCollectAddress": true,
        "metadata": {
                "key1": "value1",
                "key2": "value2"
        }
    }
}

Event Type 枚举

CHARGE_SUCCEEDED,
CHARGE_FAILED,
CHARGE_CHARGED_BACK,
CHARGE_REFUND_SUCCEEDED,
CHARGE_REFUND_FAILED;

签名

商户收到的回调信息都带有HMAC-SHA256算法生成的签名, 签名内容在http header的 "Liquido-Signature" 字段。
header中除了签名内容本身，还包含签名算法和生成签名的时间戳, 结构如下: 

algorithm=HmacSHA256,timestamp={{timestamp_in_seconds}},signature={{signature}}

更多细节请查看这里

Data 对象字段说明

参数 类型 描述
linkId String payment link在liquido系统的唯一id.
orderId String 商家的唯一的订单id
amount Long 支付金额。 单位分。 例如 100=1BRL
country String 国家代码
currency String 收款货币代码，长度为3个字节，如巴西: BRL
allowPaymentMethods List 声明支付页面包含哪些支付方式。 默认值是CREDIT_CARD. 已支持的支付方式查看这里
paymentStatus String 支付状态，枚举: INITIAL_STATUS, IN_PROGRESS, SETTLED.
finalPaymentMethod String 用户完成支付的支付方式.
finalStatusTime String 用户完成支付的时间，时间格式: "yyyy-MM-dd HH:mm:ss", UTC时区
finalStatusTimestamp Long 用户完成支付的时间戳。
refundTime String 退款时间，如果支付没有退款，则为null，时间格式: "yyyy-MM-dd HH:mm:ss", 时区: UTC
refundTimestamp Long 退款完成的时间戳. 如果没有退款，则为0
refunded Boolean 是否已退款
refundAmount Long 退款金额。 单位分。例如100=1BRL。
refundStatus String 退款状态，枚举: INITIAL_STATUS, IN_PROGRESS, SETTLED, FAILED.
name String 用户姓名。
email String 用户邮箱。
phone String 用户手机号。必须包含国际区号，如"+55".
documentId String 居民身份证件号，如巴西的CPF/CNPJ。不含分隔字符。
billingAddress Address Object 账单地址.
shippingAddress JSON 收货地址。
callbackUrl String 商户接收回调通知的url. 如果为空则不发送通知.
redirectUrl String 支付完成后的重定向地址，如果为空则不重定向。
description String 支付描述
needCollectAddress Boolean 值为true或者false。
expiredTime String Payment link的到期时间。
createTime String Payment link的创建时间。
updateTime String Payment link的更新时间。
metadata JSON 商户预留字段

BillingAddress 对象字段说明

参数 类型 描述
zipCode String 邮政编码，如巴西的CEP
state String 州，缩写，如圣保罗是SP
city String 城市.
district String 区县.
street String 街道.
number String 门牌号.
complement String 补充信息.
country String 国家代码.

ShippingAddress 对象字段说明

参数 类型 描述
name String 收货人姓名。
countryCode String 国家编号。
province String 省份或者州。
city String 城市。
postalCode String 邮编。
line1 String 地址详情。
line2 String 地址详情。
回到页面顶部