跳转至

退款

退款过程可能是同步的，也可能是异步的，最佳实践是根据回调更新退款状态。每个payment link只允许成功退款一次(失败可以重试)，支持部分退款。

请求

POST /v2/cashier/payment-link/refund

Headers
{
    "Content-Type": "application/json",
    "Authorization": "Bearer {{access_token}}",
    "x-api-key": "{{api_key}}"
}
Body
{
    "linkId": "{{link_id}}",
    "refundAmount": 9000,
    "reason": "refund test",
    "additionalInfo": {
        "bankTransferAccountInfo": {
            "bankCode": "332",
            "beneficiaryName": "antonio silva",
            "bankAccountNumber": "286435",
            "bankAccountType": "CHECKING",
            "bankBranchId": "0001",
            "ispb": "13140088",
            "document": {
                "documentId": "60123456789",
                "type": "CPF"
            }
        }
    }
}
Content-Type: application/json
{
    "code": 0,
    "message": "success",
    "data": {
        "linkId": "egGFE9mdsSa6DM5YwNGY5w",
        "orderId": "2022-12-15T14:07:00-01",
        "amount": 9999,
        "currency": "BRL",
        "country": "BR",
        "paymentStatus": "SETTLED",
        "callbackUrl": "https://your-domain/callback/",
        "redirectUrl": "https://your-domain/checkout-page",
        "description": "this is a test payment",
        "finalPaymentMethod": "PIX",
        "finalStatusTimestamp": 1671104207,
        "finalStatusTime": "2022-12-15 19:36:47",
        "refundAmount": 9000,
        "refundStatus": "IN_PROGRESS",
        "refundTime": "2022-12-15 19:38:47",
        "refundTimestamp": 1671104327,
        "email": "liquido-test@gmail.com",
        "phone": "+5511999999999",
        "allowPaymentMethods": [
            "CREDIT_CARD",
            "PIX",
            "BOLETO",
            "BANK_TRANSFER_BR"
        ],
        "billingAddress": {
            "zipCode": "04849333",
            "state": "SP",
            "city": "sao paulo",
            "district": "Jardim Gaivotas",
            "street": "Rua 9 de setembro",
            "number": "15",
            "country": "BR",
            "complement": "casa"
        },
        "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
    }
}

=== "Http状态码400响应" 

```json
{
    "code": 400,
    "message": "paymentLink unpaid. id: {{ link_id }}",
    "data": {
        "errorMessage": "paymentLink unpaid. id: {{ link_id }}"
    }
}
```

Request Body 字段说明

参数 必填 类型 描述
linkId String 支付链接唯一id.
refundAmount String 退款金额，缺省时默认全额退款。
reason String 退款理由.
additionalInfo JSON 额外信息。例如用户接收退款的账户信息。

AdditionalInfo 对象字段说明

参数 类型 描述
bankTransferAccountInfo JSON 用户银行账号信息。

BankTransferAccountInfo 对象字段说明

参数 类型 描述
bankCode String 银行代码
beneficiaryName String 受益人名称，例如 BRL_LIQUIDO
bankAccountNumber String 受益人账号
bankBranchId String 银行分行Id
bankAccountType String 受益人账号类型，例如 ContaCorrente
ispb String 银行的ISPB, 用途和缩写bankCode一致, 8位数字
document String 可确认身份的证件

Document 对象字段说明

参数 必填 类型 描述
documentId String 证件号码
type String 证件类型

Response Body 字段说明

参数 类型 描述
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.
email String 用户邮箱。
phone String 用户手机号。必须包含国际区号，如"+55".
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的更新时间。

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 地址详情。
回到页面顶部