跳到主要内容

创建一个结账

要使用 Payfect API 创建一个结账，您需要对 /checkouts 端点发出一个 POST 请求。在这个请求中，您需要包含所有相关的结账信息，比如货币和发票项目。

Endpoint​

POST /checkouts/

Fields​

Field NameTypeRequiredDescription
client_reference_idStringNoClient reference id.
currencyStringYesCurrency code (usdt).
invoice_itemsArrayYesList of invoice items.
success_urlStringNoURL to redirect on success.
cancel_urlStringNoURL to redirect on cancel.
callback_urlStringNoURL to send a callback notification upon successful completion of the charge.
payment_method_dataObjectNoData regarding the payment method chosen for the transaction.

Example Request Body​

{
    "client_reference_id": "5ae50223-e455-4a72-a48d-fe7d85800e64",
    "currency": "usdt",
    "invoice_items": [{
        "price_data": {
            "product_data": {
                "name": "Standard Plan",
                "description": "A standard plan",
                "images": [
                    "https://google.com.tw/images/123"
                ],
            },
            "currency": "usdt",
            "unit_amount": "20.5",
        },
        "quantity": 1,
    }],
    "success_url": "https://example.com/success",
    "cancel_url": "https://example.com/cancel",
    "callback_url": "https://example.com/callback",
    "payment_method_data": {
        "type": "cryptopaymentmethoddetail",
        "paymentMethodDetail": {
            "currency": "usdt",
            "network": "tron"
        }
    }
}

Response Structure​

Create a Checkout API 调用的响应返回一个包含多个字段的 JSON 对象。下面是每个字段的详细描述：

Field NameTypeDescription
idStringUnique identifier for the checkout session.
merchantObjectContains merchant's id and name.
nameCollectionBooleanIndicates if the customer name is collected.
emailCollectionBooleanIndicates if the customer email is collected.
phoneNumberCollectionBooleanIndicates if the customer phone number is collected.
shippingAddressCollectionObjectDetails of the shipping address collection.
invoiceItemsArrayArray of invoice items included in the checkout. Each item contains id, price, priceData, quantity and amount.
amountTotalStringTotal amount of the checkout session.
statusStringCurrent status of the checkout session. See Status Values below for more details.
createdAtStringTimestamp of session creation.
updatedAtStringTimestamp of the last update.
clientReferenceIdStringClient reference ID if provided.
currencyStringCurrency code of the session (e.g., 'usdt').
successUrlStringURL to redirect to on success.
cancelUrlStringURL to redirect to on cancel.
expiresAtStringExpiration timestamp for the session.
paymentIntentStringUnique identifier for the payment intent.
paymentMethodTypesArrayList of available payment method types (e.g., 'crypto', 'card').
paymentMethodOptionsObjectOptions available for the payment methods.
urlStringURL of the checkout session.
metadataObjectAdditional metadata related to the checkout.
isLivemodeBooleanIndicates if the session is in live mode.

Status Values​

响应中的 status 字段表示结账会话的当前状态。可能的值包括：

  • open: 结帐当前处于开放状态，等待完成。
  • complete: 结帐已成功完成。
  • expired: 结帐已过期，不再有效。

Example Response​

{
  "id": "ed8d24aa-a860-426b-8e56-87cb9f55a081",
  "merchant": {
    "id": "bf065cc8-343d-4419-be7d-ed2190f1df4d",
    "name": "Payfect Finance"
  },
  "nameCollection": false,
  "emailCollection": false,
  "phoneNumberCollection": false,
  "shippingAddressCollection": null,
  "invoiceItems": [
    {
      "id": "ee05d205-e4cc-42bd-8897-03c92674c57a",
      "price": "3bababfe-5ba8-4afb-84ca-d62c6933704b",
      "quantity": 1,
      "amount": "20.00"
    }
  ],
  "amountTotal": "20.00",
  "status": "open",
  "createdAt": "1690532072.288761",
  "updatedAt": "1690532073.498443",
  "clientReferenceId": null,
  "currency": "usdt",
  "successUrl": "https://example.com/success",
  "cancelUrl": "https://example.com/cancel",
  "expiresAt": "1703939166000",
  "paymentIntent": "b7c30e83-5439-47b2-ac4d-81c64c1d0174",
  "paymentMethodTypes": [
    "crypto",
    "card"
  ],
  "paymentMethodOptions": {
    "crypto": [
      {
        "currency": {
          "value": "usdt",
          "name": "Tether",
          "logo": "/static/images/cryptos/usdt.png"
        },
        "networks": [
          {
            "value": "tron",
            "name": "Tron (TRC20)"
          }
        ]
      }
    ],
    "card": null
  },
  "url": "https://buy-dev.payfect.finance/checkouts/ed8d24aa-a860-426b-8e56-87cb9f55a081",
  "metadata": null,
  "isLivemode": false
}

Example​

curl -X POST https://api.payfect.finance/api/v1/checkouts/ \
     -H 'Authorization: Api-Key 5a31f3a4-279c-11ee-be56-0242ac120002' \
     -H 'Content-Type: application/json' \
     -d '{
         "client_reference_id": "6befb0e4-e9a0-4151-8999-8b67eae19553",
         "currency": "CNY",
         "invoice_items": [{
             "price_data": {
                 "currency": "TWD",
                 "product_data": {
                     "name": "Standard Plan",
                     "description": "A standard plan",
                     "images": ["https://i.imgur.com/EHyR2nP.png"]
                 },
                 "unit_amount": "20"
             },
             "quantity": 1
         }],
         "success_url": "https://example.com/success",
         "cancel_url": "https://example.com/cancel",
         "callback_url": "https://example.com/callback",
         "payment_method_data": {
             "type": "cryptopaymentmethoddetail",
             "paymentMethodDetail": {
                 "currency": "TWD",
                 "network": "tron"
             }
         }
     }'