亮色模式

API - 退款

POST/v3/merchants/<merchant_id>/payments/<original_transaction_id>/refunds

:::tip[]
当交易发生之后一段时间内，由于用户或者商家的原因需要退款时，商家可以通过退款接口将支付款退还给用户，连连全球收单将在收到退款请求并且验证成功之后，按照退款规则将支付款按原路退回用户。

连连全球收单支持单笔交易分多次退款，多次退款需要提交原支付订单的订单号和设置不同的退款请求号。一笔退款失败后重新提交，要保证重试时退款请求号不能变更，防止该笔交易重复退款。同一笔交易累计提交的退款金额不能超过原始交易总金额。

退款成功判断说明：接口返回refund_status = RS为退款成功；refund_status = RP为退款处理中，需要通过退款查询接口进一步确认退款状态，详情可查看退款结果查询。注意，接口中return_code = SUCCESS，仅代表本次退款请求成功，不代表退款成功。

签名构建因子为入参列表中所有参数；
访问时需要将替换为商户号，为商户支付交易ID；
:::

环境域名地址

生产环境：https://gpapi.lianlianpay.com/v3/merchants/<merchant_id>/payments/<original_transaction_id>/refunds
沙箱环境：https://celer-api.LianLianpay-inc.com/v3/merchants/<merchant_id>/payments/<original_transaction_id>/refunds

接口协议结构体

详情可查看请求与响应结构

请求参数

Header 参数

signature

string

签名

必需

示例值:

XJqQTCs1QTsp+xO3iWrEMhMZUF9Wt+s2XTilT48lyv3zCmJS1+twA9cYsq9Bg9hfTnOFziCaU0OD3ddYWTMRf13uyLjwwOKD6LWyBCd+17Fq4bBdFcCwiuA6ZUkXbIWKiLACf8gY0JkKpuEvXSSrvHcpS9MPakuXKKwOBRY1UXBhWr2bL3qr8r4bLUk1A3 5ZU7Oj5r2xZV3JrdeFYqBLss1jbXNT9bS4J5JFoFKw/xBzoBkYh7btm28b8i8Q5lY2Vu7vZVK+BGKfBff2PQOJ347VGyR3+ch4qrw0ABRC52jEycWWoGQbnzs6W8DwBGg64/aR7GpNz9sHIy6YW8KwZg==

timezone

string

时区

必需

示例值:

Asia/Hong_Kong

timestamp

string

必需

格式化时间戳，格式为：yyyyMMddHHmmss

示例值:

20211022160000

Content-Type

string

必需

示例值:

application/json

merchant_transaction_id

string

商户退款交易ID

必需

由商户自定义，保证在商户端唯一

<= 64 字符

示例值:

20200808000066666

merchant_id

string

商户号

必需

由连连全球收单创建分配

<= 32 字符

示例值:

202103310000001001

sub_merchant_id

string

站点号

必需

由连连全球收单创建分配

<= 32 字符

示例值:

202103313321536404

merchant_refund_time

string

商户退款时间

必需

格式为：yyyyMMddHHmmss

<= 14 字符

示例值:

20221231135923

original_transaction_id

string

原商户支付交易ID

必需

<= 64 字符

示例值:

20200808000000008

notification_url

string

退款结果通知地址

可选

用于商户服务端接收退款结果通知的地址

<= 1024 字符

示例值:

https://acquiring.lianlianpay.com/notification

refund_data

object (REFUNDREQUESTREFUNDDATA)

退款数据

必需

refund_currency_code

string

退款币种

必需

通常情况下退款币种与支付币种相同

<= 3 字符

示例值:

USD

refund_amount

number

退款金额

必需

支持多次退款，累计退款金额不能大于原交易总金额；
提示：当天的交易只允许全额退款；

>= 0.01

示例值:

88.88

card

object (CARD)

银行卡信息

可选

支付方式为pix，boleto时必传；
仅适用于线下支付场景的退款or无法原路退回银行卡等情况；

reason

string

退款原因描述

可选

<= 512 字符

{
  "merchant_id": "2022010406411679",
  "merchant_refund_time": "20241107154346",
  "merchant_transaction_id": "test2022010408460285106",
  "notification_url": "https://test.merchant.com/v1/test2022010408460285106",
  "original_transaction_id": "2022010408460285106",
  "refund_data": {
    "refund_amount": "13.50",
    "refund_currency_code": "USD"
  }
}

示例代码

返回响应

成功(200)

HTTP 状态码: 200

内容格式: JSONapplication/json

return_code

string

返回码

必需

返回码

return_message

string

返回消息

必需

返回消息

trace_id

string

追踪号

必需

需要技术支持时候，请提供至LianLian Pay技术人员

order

object (REFUNDRESPONSE)

退款数据

必需

退款提交成功才有返回值

ll_transaction_id

string

连连退款订单号

必需

<= 64 字符

merchant_transaction_id

string

商户退款交易ID

必需

<= 64 字符

original_transaction_id

string

原商户支付交易ID

必需

<= 64 字符

refund_data

object (REFUNDRESPONSEREFUNDDATA)

退款数据

必需

{
  "order": {
    "llTransactionId": "2022010406411679",
    "merchant_transaction_id": "test2022010408460285106",
    "original_transaction_id": "10167419",
    "refund_data": {
      "actual_refund_amount": "1499.00",
      "actual_refund_currency_code": "USD",
      "reason": "do not like the goods",
      "refund_amount": "1499.00",
      "refund_currency_code": "USD",
      "refund_status": "PP",
      "refund_time": "20220104084604",
      "settlement_currency_code": "USD"
    }
  },
  "return_code": "SUCCESS",
  "return_message": "Success",
  "trace_id": "4109.101.16412859638116385"
}