退款 API

本指南全面介绍了 Codapay 的退款 API。文档详细说明了商户如何通过编程方式发起退款、查询退款状态以及处理退款通知。

退款场景概览

Codapay 仅支持对已完成支付的订单进行退款操作。若请求退款时支付未完成或已取消，系统将返回错误响应

1. 退款集成流程

已完成支付的退款处理

已取消支付的退款处理

2. 创建退款

接口 URL

POST {domain}/airtime/api/restful/v2.0/Payment/createRefund.json

示例

{
  "refundRequest": {
    "apiKey": "<your_api_key>",
    "txnId": 1234567890,
    "country": "ID",
    "projectId": 100,
    "customerEmail": "[e-mail]"
  }
}

请求参数

参数	类型	必填	描述
refundRequest	Object	是	有效的 JSON 对象
refundRequest.apiKey	String	是	Coda 提供的 API 密钥
refundRequest.txnId	Numeric	是	需要退款的交易 ID
refundRequest.country	String	否	ISO 3166 国家代码
refundRequest.projectId	Numeric	是	唯一的项目 ID
refundRequest.customerEmail	String	否	用户邮箱地址

响应示例

{
  "refundResult": {
    "id": "rfl_sg195468b7c6c0000",
    "createdAt": "2023-03-08T15:30:00.000000000Z",
    "statusCode": "accepted",
    "type": "full",
    "txnId": 1234567890,
    "amountValue": 40000,
    "amountCurrency": "IDR"
  }
}

响应字段

参数	类型	说明
refundResult	Object	JSON 对象
refundResult.id	String	退款 ID (Refund ID)
refundResult.createdAt	String	时间戳（ISO 8601 格式） 支持格式： YYYY-MM-DDThh:mm:ss.ssssssZ（微秒级） YYYY-MM-DDThh:mm:ss.sssssssssZ（纳秒级）
refundResult.statusCode	String	状态：accepted、succeeded 或 failed
refundResult.finalizedAt	String	退款完成时的可选时间戳 支持格式： YYYY-MM-DDThh:mm:ss.ssssssZ（微秒级） YYYY-MM-DDThh:mm:ss.sssssssssZ（纳秒级） *如为 null，该字段不会返回
refundResult.type	String	退款类型，始终为 "full"
refundResult.txnId	Numeric	已退款的交易 ID
refundResult.amountValue	Numeric	退款金额
refundResult.amountCurrency	String	退款币种

错误响应示例

{
  "refundResult": {
    "resultCode": 551
    "resultDesc": "Duplicate Refund Request"
  }
}

错误响应字段

参数	类型	说明
refundResult	Object	JSON 对象
refundResult.resultCode	Numeric	错误代码
refundResult.resultDesc	String	错误描述

错误代码

代码	说明
103	API 密钥无效、未找到商户或邮箱无效
206	未找到交易，或交易无效
551	重复的退款请求
102	内部服务器错误

3. 查询退款状态

接口 URL

POST {domain}/airtime/api/restful/v2.0/Payment/retrieveRefund.json

示例

{
  "retrieveRefundRequest": {
    "apiKey": "<your_api_key>",
    "country": "ID",
    "projectId": 100,
    "refundId": "rfl_sg1955a7330200033"
  }
}

请求参数

参数	类型	是否必填	说明
refundRequest	Object	是	有效的 JSON 对象
refundRequest.apiKey	String	是	Coda 提供的 API 密钥
refundRequest.country	String	否	ISO 3166 国家代码
refundRequest.projectId	Numeric	是	唯一的项目 ID
refundRequest.refundId	String	是	查询的退款请求 ID

响应

与 createRefund 接口中的 refundResult 对象结构相同。

4. 退款通知回调

Codapay 会向已配置的通知 URL 发送 webhook，告知退款状态。

Codapay 请求

GET {merchantCallbackUrl}?EventType=refund&Id=<refund_id>&CreatedAt=<ts>&StatusCode=accepted&FinalizedAt=<ts>&Type=full&TxnId=<txn_id>&AmountValue=<amount>&AmountCurrency=<currency>&OrderId=<orderId>&ResultCode=0&Checksum=<checksum>

Webhook 响应规范

ResultCode=0

关键字段

字段	类型	说明
EventType	String	事件类型，本接口为 "refund"
Id	String	退款 ID (Refund ID)
CreatedAt	String	退款创建时间戳（ISO 8601 格式） 支持格式： YYYY-MM-DDThh:mm:ss.ssssssZ（微秒级） YYYY-MM-DDThh:mm:ss.sssssssssZ（纳秒级）
StatusCode	String	状态：accepted、succeeded 或 failed
FinalizedAt	String	退款完成时间戳（ISO 8601 格式） 支持格式： YYYY-MM-DDThh:mm:ss.ssssssZ（微秒级） YYYY-MM-DDThh:mm:ss.sssssssssZ（纳秒级）
Type	String	退款类型，始终为 "full"
TxnId	String	交易 ID
AmountValue	Float	退款金额
AmountCurrency	String	退款币种
OrderId	String	商户订单号
ResultCode	Integer	支付结果代码（0 表示成功） 0: 成功 431: 处理中 216: 处理中 481: 处理中 其他: 失败
Checksum	String	校验码，用于数据验证

校验和生成

MD5(eventType + apiKey + txnId + orderId + resultCode + statusCode)

5. 沙盒环境测试

退款

1. 在沙盒环境完成一笔支付

2. 使用该交易 ID 发起退款请求

3. 通过 retrieveRefund 接口查询退款状态

4. 如需模拟最终状态，请联系 Codapay 支持团队

请求示例

创建退款

curl --location 'https://sandbox.codapayments.com/airtime/api/restful/v2.0/Payment/createRefund.json' \
--header 'Content-Type: application/json' \
--data-raw '{
  "refundRequest": {
    "country": "ID",
    "apiKey": "<test_key>",
    "txnId": "740976157910166864",
    "projectId": 43
  }
}'

查询退款

curl --location 'https://sandbox.codapayments.com/airtime/api/restful/v2.0/Payment/retrieveRefund.json' \
--header 'Content-Type: application/json' \
--data '{
  "retrieveRefundRequest": {
    "country": "ID",
    "apiKey": "<test_key>",
    "projectId": 43,
    "refundId": "rfl_sg1955a7330200033"
  }
}'