API

一次 POST。一笔支付。

REST、JSON，使用 API Key 鉴权。沙箱环境无需预先审批即可使用。

鉴权

每个请求都在 Authorization: Bearer 请求头中使用 API Key——沙箱环境用 sk_test_...，生产环境用 sk_live_...。

bash

curl https://api.tamino.com.br/v1/payments \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json"

创建支付

支付创建后状态为 pending，随着服务商确认而变化。

Request

POST /v1/payments

{
  "amount": 15000,
  "currency": "BRL",
  "method": "pix"
}

Response

200 OK

{
  "id": "pay_xxxxxxxxx",
  "status": "pending"
}

查询支付

同一资源，随时可通过 id 查询。

json

GET /v1/payments/pay_xxxxxxxxx

{
  "id": "pay_xxxxxxxxx",
  "status": "approved",
  "amount": 15000,
  "currency": "BRL",
  "method": "pix"
}

幂等性

在任何可变更请求中携带 Idempotency-Key——使用相同的键重发会返回已计算好的响应，绝不会重复执行该操作。

bash

curl -X POST https://api.tamino.com.br/v1/payments \
  -H "Authorization: Bearer sk_test_..." \
  -H "Idempotency-Key: 8f14e45f-ceea-..." \
  -d '{ "amount": 15000, "currency": "BRL", "method": "pix" }'

错误处理

所有错误使用统一的响应结构，并附带 correlationId 便于支持团队追踪。

json

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "amount must be a positive integer.",
    "correlationId": "c7a1..."
  }
}