空中云付文档:技术参考手册,深度解析接口原理
随着移动支付和云计算技术的快速发展,越来越多的企业开始采用云端支付解决方案来提高支付效率和安全性。空中云付作为一种先进的云端支付平台,提供了丰富的API接口,方便开发者快速集成支付功能。本文旨在详细介绍空中云付文档接口操作并解答常见问题,帮助开发者更好地理解和使用空中云付。
一、空中云付文档接口概述
空中云付接口是一组基于HTTP协议的RESTful API,支持多种编程语言调用。通过这些接口,开发者可以实现支付、查询、退款等功能。空中云付接口具有高可用性、高安全性和高扩展性,适用于各种规模的商业应用。
二、空中云付文档接口操作
2.1 接口认证
为了确保接口调用的安全性,空中云付采用了OAuth 2.0认证机制。开发者需要在调用接口前获取访问令牌(Access Token)。
获取Access Token
请求URL: https://api.cloudpay.com/oauth2/token
请求方法: POST
请求参数:
参数名 | 类型 | 必填 | 描述 |
client_id | string | 是 | 客户端ID |
client_secret | string | 是 | 客户端密钥 |
grant_type | string | 是 | 授权类型,固定为”client_credentials” |
请求示例:
{
"client_id": "your_client_id",
"client_secret": "your_client_secret",
"grant_type": "client_credentials"
}
返回结果:
参数名 | 类型 | 描述 |
access_token | string | 访问令牌 |
expires_in | int | 过期时间(秒) |
token_type | string | 令牌类型,固定为”Bearer” |
返回示例:
{
"access_token": "your_access_token",
"expires_in": 3600,
"token_type": "Bearer"
}
2.2 接口调用流程
- 获取Access Token: 使用客户端ID和密钥获取Access Token。
- 调用业务接口: 使用获取到的Access Token调用具体的业务接口。
- 处理返回结果: 根据接口返回的结果进行相应的业务处理。
2.3 接口参数说明
2.3.1 支付接口
请求URL: https://api.cloudpay.com/v1/payment
请求方法: POST
请求头:
参数名 | 类型 | 必填 | 描述 |
Authorization | string | 是 | Bearer Access Token |
Content-Type | string | 是 | 固定为”application/json” |
请求参数:
参数名 | 类型 | 必填 | 描述 |
order_id | string | 是 | 订单ID |
amount | int | 是 | 支付金额(分) |
currency | string | 是 | 货币类型,如”CNY” |
subject | string | 是 | 订单标题 |
body | string | 否 | 订单描述 |
notify_url | string | 是 | 异步通知URL |
return_url | string | 否 | 同步返回URL |
请求示例:
{
"order_id": "202310010001",
"amount": 1000,
"currency": "CNY",
"subject": "测试订单",
"body": "这是一个测试订单",
"notify_url": "https://yourdomain.com/notify",
"return_url": "https://yourdomain.com/return"
}
返回结果:
参数名 | 类型 | 描述 |
code | int | 返回码 |
message | string | 返回信息 |
data | object | 返回数据 |
data.payment_id | string | 支付ID |
data.payment_url | string | 支付链接 |
返回示例:
{
"code": 0,
"message": "success",
"data": {
"payment_id": "202310010001",
"payment_url": "https://pay.cloudpay.com/202310010001"
}
}
2.3.2 查询接口
请求URL: https://api.cloudpay.com/v1/query
请求方法: POST
请求头:
参数名 | 类型 | 必填 | 描述 |
Authorization | string | 是 | Bearer Access Token |
Content-Type | string | 是 | 固定为”application/json” |
请求参数:
参数名 | 类型 | 必填 | 描述 |
payment_id | string | 是 | 支付ID |
请求示例:
{
"payment_id": "202310010001"
}
返回结果:
参数名 | 类型 | 描述 |
code | int | 返回码 |
message | string | 返回信息 |
data | object | 返回数据 |
data.status | string | 支付状态 |
data.amount | int | 支付金额(分) |
data.currency | string | 货币类型 |
data.subject | string | 订单标题 |
data.body | string | 订单描述 |
返回示例:
{
"code": 0,
"message": "success",
"data": {
"status": "SUCCESS",
"amount": 1000,
"currency": "CNY",
"subject": "测试订单",
"body": "这是一个测试订单"
}
}
2.3.3 退款接口
请求URL: https://api.cloudpay.com/v1/refund
请求方法: POST
请求头:
参数名 | 类型 | 必填 | 描述 |
Authorization | string | 是 | Bearer Access Token |
Content-Type | string | 是 | 固定为”application/json” |
请求参数:
参数名 | 类型 | 必填 | 描述 |
payment_id | string | 是 | 支付ID |
refund_amount | int | 是 | 退款金额(分) |
reason | string | 否 | 退款原因 |
请求示例:
{
"payment_id": "202310010001",
"refund_amount": 1000,
"reason": "用户取消订单"
}
返回结果:
参数名 | 类型 | 描述 |
code | int | 返回码 |
message | string | 返回信息 |
data | object | 返回数据 |
data.refund_id | string | 退款ID |
data.status | string | 退款状态 |
返回示例:
{
"code": 0,
"message": "success",
"data": {
"refund_id": "202310010001R",
"status": "PROCESSING"
}
}
2.4 接口返回结果
所有接口的返回结果都包含code
和message
字段,用于表示接口调用的状态。code
为0表示成功,非0表示失败。data
字段包含具体的返回数据,不同接口的data
字段结构不同。
2.5 错误码说明
错误码 | 描述 |
0 | 成功 |
1001 | 参数错误 |
1002 | 认证失败 |
1003 | 支付失败 |
1004 | 查询失败 |
1005 | 退款失败 |
1006 | 系统错误 |
三、常见问题解答(FAQ)
3.1 如何获取Access Token?
答:通过OAuth 2.0认证机制,使用客户端ID和密钥向https://api.cloudpay.com/oauth2/token
发送POST请求,获取Access Token。
3.2 支付接口的notify_url
和return_url
有什么区别?
答:notify_url
用于接收异步通知,支付完成后,空中云付会向该URL发送支付结果通知。return_url
用于同步返回,支付完成后,用户会被重定向到该URL。
3.3 如何处理支付结果通知?
答:支付完成后,空中云付会向notify_url
发送POST请求,请求体包含支付结果信息。开发者需要在该URL对应的接口中处理支付结果,并返回success
表示处理成功。
3.4 如何查询支付状态?
答:使用查询接口,向https://api.cloudpay.com/v1/query
发送POST请求,传入支付ID,即可查询支付状态。
3.5 退款接口的refund_amount
可以大于支付金额吗?
答:不可以。refund_amount
必须小于或等于支付金额,否则会返回参数错误。
3.6 如何处理退款结果通知?
答:退款完成后,空中云付会向notify_url
发送POST请求,请求体包含退款结果信息。开发者需要在该URL对应的接口中处理退款结果,并返回success
表示处理成功。
3.7 接口调用失败怎么办?
答:首先检查返回的code
和message
,根据错误码说明进行排查。如果问题仍未解决,可以联系空中云付技术支持。
四、结论
空中云付接口提供了丰富的功能和灵活的调用方式,能够满足各种支付场景的需求。通过本文的介绍,开发者可以快速掌握空中云付接口的使用方法,并解决常见问题。希望本文能为开发者提供有价值的参考,助力业务发展。