> ## Documentation Index
> Fetch the complete documentation index at: https://docs.didit.me/llms.txt
> Use this file to discover all available pages before exploring further.

# 充值额度 API：通过 Stripe 为 Didit 余额充值

> 创建 Stripe 结账会话，为 Didit 余额充值 $50 至 $20,000，按面值计入，适用于免费版、Growth 版和 Scale 版套餐。充值额度有效期 12 个月。



充值额度提示词
        将提示词复制到剪贴板



      
      

\<pre>

\``Goal: Start a manual credit top-up by creating a hosted Stripe Checkout session. Once Stripe processes the payment, Didit's invoice.paid webhook handler credits the organization's balance.

Endpoint: POST https://verification.didit.me/v3/billing/top-up/
Auth header: x-api-key: <DIDIT_API_KEY>
Content-Type: application/json

Request body:
\- amount_in_dollars (number, REQUIRED) — USD amount to charge, from $50 MINIMUM to $20,000 MAXIMUM. The balance receives the same amount: no discount or bonus. Tax is added automatically at checkout based on billing address.
\- success_url (URI, optional) — Stripe redirects here after successful payment. Currently defaults to `https://console.didit.me`. Pass a working URL explicitly; the default host is unavailable. Append literal placeholder {CHECKOUT_SESSION_ID} if you want Stripe to substitute the session id.
\- cancel_url (URI, optional) — Stripe redirects here when the customer aborts. Currently defaults to `https://console.didit.me`. Pass a working URL explicitly; the default host is unavailable.

curl:
curl -X POST 'https://verification.didit.me/v3/billing/top-up/' \
-H 'x-api-key: YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{
"amount_in_dollars": 500,
"success_url": "https://yourapp.com/billing/success",
"cancel_url": "https://yourapp.com/billing/cancel"
}'

Response 200:
\{
"checkout_session_id": "cs_test_a1B2c3D4e5F6g7H8i9J0",
"checkout_session_url": "https://checkout.stripe.com/c/pay/cs_test_..."
}
Redirect the customer's browser to checkout_session_url (or hand it off to your billing admin out-of-band) to complete payment.

Full flow:
1\. POST /v3/billing/top-up/ with amount_in_dollars and explicit success_url and cancel_url values.
2\. Redirect to checkout_session_url.
3\. Customer pays on Stripe-hosted page.
4\. Stripe redirects to success_url (or cancel_url on abort).
5\. Didit receives invoice.paid webhook, increases organization balance.
6\. Poll GET /v3/billing/balance/ to confirm balance reflects the top-up.

Failure modes:
\- 400 — the body is a JSON array with one message:
\["amount_in_dollars is required."]
\["amount_in_dollars must be a number."]
\["Amount must be at least $50."]
\["Amount must be at most $20,000."]
\["You have an annual plan. Contact your account manager to top up."]  // Enterprise annual-contract orgs cannot top up: usage beyond the contract credit is invoiced as overage.
\- 401 — missing/malformed x-api-key.
\- 403 — key valid but cannot create top-up sessions for this organization.
\- 429 — rate-limited.

Notes:
\- Top-ups are available on the Free, Growth and Scale plans, from $50 to $20,000 each. They are added at face value (pay $20,000, receive $20,000; no discount or bonus), pay for every product, and last 12 months. Each check uses the month's plan credit first, then the oldest top-up.
\- Auto top-up amounts, set in Console → Billing, follow the same $50 to $20,000 range.
\- The Stripe Checkout session is single-use, but calling this endpoint repeatedly creates NEW sessions — track completion on your side via success_url/cancel_url to avoid duplicate charges.
\- When the cardholder pays with card / SEPA / US ACH, Stripe attaches the payment method with setup_future_usage=off_session so Didit can later auto-charge it for auto-refill.
\- The organization must already have a Stripe customer set up (created automatically the first time the org configures billing).

For end-to-end Didit integration, paste in the full prompt at /integration/integration-prompt.``

\</pre>



      
      

粘贴到



## OpenAPI

````yaml zh/openapi-25.json POST /v3/billing/top-up/
openapi: 3.0.0
info:
  version: 3.0.0
  title: Didit Verification API
  description: 身份证件验证 API。使用 x-api-key 请求头进行身份验证。
servers:
  - url: https://verification.didit.me
security: []
tags: []
paths:
  /v3/billing/top-up/:
    post:
      tags:
        - Billing
      summary: 充值额度
      description: >-
        通过托管的 Stripe Checkout 会话添加额度（每次充值 **\$50 至 \$20,000**）。Free、Growth 和
        Scale 套餐支持充值，按面值添加且无折扣或赠送，有效期为 12 个月；Enterprise 年度合约无法充值。将客户重定向至返回的
        `checkout_session_url`。
      operationId: billing_top_up
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - amount_in_dollars
              properties:
                amount_in_dollars:
                  type: number
                  minimum: 50
                  maximum: 20000
                  description: >-
                    扣款金额，以 USD 计。**必须在 50 到 20,000 之间。**
                    余额将增加相同金额，无任何折扣或奖励。结账时将根据客户的账单地址自动加计税费。
                success_url:
                  type: string
                  format: uri
                  description: >-
                    支付成功后托管结账将客户重定向到的 URL。当前默认为
                    `https://console.didit.me`。请显式传入可用 URL；默认主机不可用。如果您希望托管结账替换会话
                    ID，请附加字面量占位符 `{CHECKOUT_SESSION_ID}`。
                cancel_url:
                  type: string
                  format: uri
                  description: >-
                    当客户中止或关闭结账窗口时，托管结账将客户重定向到的 URL。当前默认为
                    `https://console.didit.me`。请显式传入可用 URL；默认主机不可用。
            examples:
              Minimum top-up:
                value:
                  amount_in_dollars: 50
              Custom amount with redirects:
                value:
                  amount_in_dollars: 500
                  success_url: https://yourapp.com/billing/top-up/success
                  cancel_url: https://yourapp.com/billing/top-up/cancel
      responses:
        '200':
          description: 托管结账会话已创建。将用户重定向至 `checkout_session_url` 以完成支付。
          content:
            application/json:
              schema:
                type: object
                required:
                  - checkout_session_id
                  - checkout_session_url
                properties:
                  checkout_session_id:
                    type: string
                    description: 托管结账会话标识符（例如 `cs_test_a1B2c3...`）。用于服务端对账。
                  checkout_session_url:
                    type: string
                    format: uri
                    description: 单次使用的托管支付页面 URL。将客户重定向至此处以完成支付。
              examples:
                Created:
                  value:
                    checkout_session_id: cs_test_a1B2c3D4e5F6g7H8i9J0
                    checkout_session_url: >-
                      https://checkout.example.com/c/pay/cs_test_a1B2c3D4e5F6g7H8i9J0
        '400':
          description: >-
            无效的 payload：缺少金额、金额不是数字、低于 \$50 的最低限额或高于 \$20,000
            的最高限额，或者该组织使用的是企业年度合同。错误体为 JSON 数组。
          content:
            application/json:
              examples:
                Missing amount:
                  value:
                    - amount_in_dollars is required.
                Not a number:
                  value:
                    - amount_in_dollars must be a number.
                Below minimum:
                  value:
                    - Amount must be at least $50.
                Above maximum:
                  value:
                    - Amount must be at most $20,000.
                Annual plan:
                  value:
                    - >-
                      You have an annual plan. Contact your account manager to
                      top up.
        '403':
          description: >-
            API 密钥缺失、无效或已撤销，或者该密钥无法为此组织创建充值会话。缺少密钥返回 `403`；错误、已撤销或已过期的密钥返回
            `401`。
          content:
            application/json:
              examples:
                Forbidden:
                  value:
                    detail: You do not have permission to perform this action.
        '429':
          description: 超出速率限制；请退避并在 `Retry-After` 指定的间隔后重试。
          content:
            application/json:
              examples:
                Throttled:
                  value:
                    detail: Request was throttled. Expected available in 30 seconds.
      security:
        - ApiKeyAuth: []
      x-codeSamples:
        - lang: curl
          label: curl
          source: |-
            curl -X POST 'https://verification.didit.me/v3/billing/top-up/' \
              -H 'x-api-key: YOUR_API_KEY' \
              -H 'Content-Type: application/json' \
              -d '{
                "amount_in_dollars": 500,
                "success_url": "https://yourapp.com/billing/success",
                "cancel_url": "https://yourapp.com/billing/cancel"
              }'
        - lang: python
          label: Python
          source: |-
            from didit import Didit

            # Reads DIDIT_API_KEY.
            client = Didit()

            result = client.billing.top_up(
                amount_in_dollars=50.0,
            )
            print(result)
        - lang: javascript
          label: Node.js
          source: |-
            import Didit from "@didit-protocol/sdk-node";

            // Reads DIDIT_API_KEY.
            const didit = new Didit();

            const result = await didit.billing.topUp({
              amount_in_dollars: 50.0,
            });
            console.log(result);
        - lang: go
          label: Go
          source: "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.Billing.TopUp(ctx, didit.BillingTopUpParams{\n\tAmountInDollars: 50.0,\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)"
        - lang: java
          label: Java
          source: |-
            import me.didit.Didit;
            import me.didit.types.BillingTopUpParams;

            // Reads DIDIT_API_KEY.
            Didit client = new Didit();

            var result = client.billing().topUp(BillingTopUpParams.builder()
                    .amountInDollars(50.0)
                    .build());
            System.out.println(result);
        - lang: php
          label: PHP
          source: |-
            <?php

            require 'vendor/autoload.php';

            use Didit\DiditClient;

            // Reads DIDIT_API_KEY.
            $didit = new DiditClient();

            $result = $didit->billing->topUp([
                'amount_in_dollars' => 50.0,
            ]);
            print_r($result->toArray());
        - lang: ruby
          label: Ruby
          source: |-
            require "didit"

            # Reads DIDIT_API_KEY.
            didit = Didit::Client.new

            result = didit.billing.top_up(amount_in_dollars: 50.0)
            puts result.to_h
        - lang: csharp
          label: .NET
          source: |-
            using System;
            using System.Text.Json;
            using Didit;

            // Reads DIDIT_API_KEY.
            using var client = new DiditClient();

            var result = await client.Billing.TopUpAsync(new BillingTopUpParams
            {
                AmountInDollars = 50.0,
            });
            Console.WriteLine(JsonSerializer.Serialize(result));
components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key
      description: >-
        您的应用 API 密钥，可在 Business Console 的“开发者 -> API
        密钥”中获取。主密钥拥有完整访问权限。指定名称的密钥可设置作用域：针对每个资源设为无权限、只读或读写，限定于特定工作流或已通过的会话、限定于
        IP 地址列表，以及设置到期日期。401 表示密钥错误、已撤销或已过期；403 表示未发送密钥、密钥无权访问该资源或操作，或请求来自其 IP
        列表之外的地址；在会话路由上返回 404 表示该会话不在该密钥允许的工作流或状态范围内。没有媒体访问权限的密钥获取到的图片、视频和 PDF
        URL 将为 null；没有会话写入权限的密钥获取到的会话链接和 token 将为 null。请参阅
        https://docs.didit.me/console/api-keys。

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.