velopayments商业支付平台

Velo Payments API 基于 REST，并使用 JSON 格式进行请求和响应。

大多数调用都使用 OAuth 2 安全性进行保护，并且需要有效的身份验证访问令牌才能成功操作。有关详细信息，请参阅身份验证部分。

以下示例中需要动态值的地方使用 {token} 格式，这表明调用者需要提供所讨论令牌的适当值（不包括 { 或 } 字符）。

在给出 curl 示例时，使用 –d @filename.json 方法，表示请求正文应放入当前目录中名为 filename.json 的文件中。本文档中的每个 curl 示例都应视为命令行上的一行，无论它们在打印中如何显示。

一旦 Velo 后台工作人员将您的组织添加为 Velo 平台沙箱中的付款人，他们将为您创建一个付款人 ID、一个 API 密钥和一个 API 机密，并以安全的方式与您共享这些信息。

您需要使用这些值对 Velo 平台进行身份验证，才能访问 API。具体步骤如下：

创建一个包含 API 密钥（例如 44a9537d-d55d-4b47-8082-1​​4061c2bcdd8）和 API 机密（例如 c396b26b-137a-44fd-87f5-34631f8fd529）的字符串，中间用冒号隔开。例如 44a9537d-d55d-4b47-8082-1​​4061c2bcdd8:c396b26b-137a-44fd-87f5-34631f8fd529

对该字符串进行 base64 编码。例如：NDRhOTUzN2QtZDU1ZC00YjQ3LTgwODItMTQwNjFjMmJjZGQ4OmMzOTZiMjZiLTEzN2EtNDRmZC04N2Y1LTM0NjMxZjhmZDUyOQ==

创建一个 HTTP授权标头，其值设置为例如 Basic NDRhOTUzN2QtZDU1ZC00YjQ3LTgwODItMTQwNjFjMmJjZGQ4OmMzOTZiMjZiLTEzN2EtNDRmZC04N2Y1LTM0NjMxZjhmZDUyOQ==

使用上面创建的 HTTP 标头执行 Velo 身份验证 REST 调用，例如通过 curl：

  curl -X POST \
  -H "Content-Type: application/json" \
  -H "Authorization: Basic NDRhOTUzN2QtZDU1ZC00YjQ3LTgwODItMTQwNjFjMmJjZGQ4OmMzOTZiMjZiLTEzN2EtNDRmZC04N2Y1LTM0NjMxZjhmZDUyOQ==" \
  'https://api.sandbox.velopayments.com/v1/authenticate?grant_type=client_credentials'

如果成功，此调用将导致200 HTTP 状态代码和响应主体，例如：

  {
    "access_token":"19f6bafd-93fd-4747-b229-00507bbc991f",
    "token_type":"bearer",
    "expires_in":1799,
    "scope":"..."
  }

身份验证成功后，响应中的 access_token 字段的值（上图以绿色表示）应在所有后续 API 调用中显示，以允许 Velo 平台验证调用者是否已经通过身份验证。

这是通过设置 HTTP 授权标头来实现的，其值设置为例如 Bearer 19f6bafd-93fd-4747-b229-00507bbc991f，如下面的 curl 示例：

  -H "Authorization: Bearer 19f6bafd-93fd-4747-b229-00507bbc991f "

如果您进行其他需要授权的 Velo API 调用但授权标头缺失或无效，那么您将收到401 HTTP 状态响应。

以下是平台可能返回的 Http 状态代码列表

| Status Code            | Description                                                                          |
| -----------------------| -------------------------------------------------------------------------------------|
| 200 OK                 | The request was successfully processed and usually returns a json response           |
| 201 Created            | A resource was created and a Location header is returned linking to the new resource |
| 202 Accepted           | The request has been accepted for processing                                         |
| 204 No Content         | The request has been processed and there is no response (usually deletes and updates)|
| 400 Bad Request        | The request is invalid and should be fixed before retrying                           |
| 401 Unauthorized       | Authentication has failed, usually means the token has expired                       |
| 403 Forbidden          | The user does not have permissions for the request                                   |
| 404 Not Found          | The resource was not found                                                           |
| 409 Conflict           | The resource already exists and there is a conflict                                  |
| 429 Too Many Requests  | The user has submitted too many requests in a given amount of time                   |
| 5xx Server Error       | Platform internal error (should rarely happen)                                       |

指南详情链接：https://apidocs.velopayments.com/#section/Http-Status-Codes