Skip to main content
C# SDK cung cấp cho các ứng dụng .NET quyền truy cập có kiểu đến REST API của Dodo Payments. Mọi phương thức API đều là bất đồng bộ và trả về một Task, request và response là các lớp có kiểu, đồng thời client sẽ tự động retry các request thất bại.

Cài đặt

Cài đặt gói từ NuGet:
SDK yêu cầu .NET Standard 2.0 trở lên và cũng đi kèm bản build cho .NET 8. SDK hoạt động với ASP.NET Core, ứng dụng console và các loại dự án .NET khác. Các ví dụ trên trang này sử dụng cú pháp C# 12, chẳng hạn như collection expressions.

Bắt đầu nhanh

Tạo một client, sau đó tạo một phiên checkout:
Nếu bạn không thiết lập BearerToken, client sẽ đọc biến môi trường DODO_PAYMENTS_API_KEY. Nếu bạn không thiết lập BaseUrl hoặc DODO_PAYMENTS_BASE_URL, client sẽ kết nối với live mode. Để sử dụng test mode, hãy xem Environments. API key của test mode chỉ hoạt động trong test mode.
Lưu API key trong biến môi trường, user secrets hoặc Azure Key Vault. Không bao giờ hardcode chúng trong mã nguồn hoặc commit chúng vào hệ thống quản lý phiên bản.

Tính năng cốt lõi

Async/Await

Mọi phương thức API đều trả về một Task và chấp nhận một CancellationToken tùy chọn.

Strong Typing

Các lớp request và response có kiểu, cùng với chú thích kiểu tham chiếu nullable.

Smart Retries

Mặc định retry hai lần, với exponential backoff, cho các lỗi kết nối và status code có thể retry.

Error Handling

Một exception class cho mỗi HTTP error status phổ biến, kèm status code và response body.

Cấu hình

Biến môi trường

Lưu API key trong một biến môi trường:
.env
Client được tạo bằng new() sẽ đọc các cài đặt từ môi trường:
Client sẽ đọc các biến môi trường này khi bạn không thiết lập property tương ứng: Nếu cả BearerToken và DODO_PAYMENTS_API_KEY đều chưa được thiết lập, client sẽ throw DodoPaymentsInvalidDataException. WebhookKey chứa webhook signing secret của bạn, nhưng C# SDK không có phương thức xác minh webhook signature. Để xác minh chúng, hãy làm theo Webhooks.

Cấu hình thủ công

Thiết lập các property trên client để ghi đè các biến môi trường:

Environments

Theo mặc định, client kết nối với live mode (https://live.dodopayments.com). Để sử dụng test mode (https://test.dodopayments.com), hãy đặt BaseUrl thành EnvironmentUrl.TestMode:

Retry

SDK sẽ retry các lỗi kết nối và response có status 408, 409, 429 hoặc 500 trở lên. Theo mặc định, SDK retry hai lần với exponential backoff. Đặt MaxRetries để thay đổi số lần retry hoặc đặt thành 0 để tắt retry:

Timeout

Theo mặc định, mỗi lần thử request sẽ timeout sau 1 phút. Timeout không bao gồm các lần retry. Đặt Timeout để thay đổi giá trị này:

Ghi đè theo từng request

Để thay đổi các cài đặt cho một lần gọi duy nhất, hãy gọi WithOptions trên client hoặc service. Phương thức này trả về một bản sao đã sửa đổi dùng chung connection pool, còn client ban đầu không thay đổi:

Các thao tác phổ biến

Các ví dụ trong phần này sử dụng client từ Quick Start.

Tạo Checkout Session

Tạo một checkout session, sau đó redirect khách hàng đến CheckoutUrl được trả về:
Mỗi checkout URL chỉ hoạt động một lần và hết hạn sau 24 giờ. Để xem mọi tùy chọn của session, hãy xem Checkout Sessions.

Quản lý khách hàng

Tạo một khách hàng bằng địa chỉ email và tên, sau đó retrieve khách hàng bằng ID:
Customers.Retrieve cũng chấp nhận ID dưới dạng string, ví dụ client.Customers.Retrieve("cus_123").

Xử lý subscription

Tạo một subscription, sau đó charge subscription đó nếu đây là on-demand subscription.
POST /subscriptions (phương thức Subscriptions.Create của SDK) đã deprecated. Phương thức này vẫn hoạt động cho các integration hiện có, nhưng integration mới nên tạo subscription thông qua một Checkout Session.
Billing chỉ yêu cầu Country, là mã quốc gia ISO gồm hai chữ cái. Customer nhận một AttachExistingCustomer để gắn customer hiện có hoặc một NewCustomer để tạo customer mới. Charge dành cho on-demand subscriptions, còn ProductPrice được tính theo đơn vị nhỏ nhất của tiền tệ.

Xử lý lỗi

Khi API trả về một error status, SDK sẽ throw một subclass của DodoPaymentsApiException, chứa các property StatusCode và ResponseBody. Exception class phụ thuộc vào status code. Tất cả exception 4xx đều kế thừa từ DodoPayments4xxException. Status 4xx không có class riêng, chẳng hạn 409, sẽ throw DodoPayments4xxException. DodoPaymentsUnexpectedStatusCodeException xử lý các status nằm ngoài phạm vi 4xx và 5xx. SDK cũng throw các exception sau:
  • DodoPaymentsIOException: Lỗi I/O hoặc network.
  • DodoPaymentsInvalidDataException: SDK không thể diễn giải dữ liệu response, chẳng hạn do thiếu một property bắt buộc.
  • DodoPaymentsException: Base class của mọi SDK exception.

Phân trang

Các phương thức list trả về một trang kết quả. Bạn có thể lặp qua từng item hoặc tự di chuyển giữa các trang.

Phân trang tự động

Paginate trả về một IAsyncEnumerable, tự fetch trang tiếp theo khi cần:

Phân trang thủ công

Để làm việc với từng trang một, hãy đọc Items, sau đó gọi HasNext() và Next():
Để đặt kích thước trang, truyền một PaymentListParams từ namespace DodoPayments.Client.Models.Payments, ví dụ client.Payments.List(new PaymentListParams { PageSize = 50 }).

Tích hợp ASP.NET Core

Đăng ký một client dưới dạng singleton trong dependency injection container và đọc API key từ configuration:
Program.cs
Thêm key vào configuration, chẳng hạn trong appsettings.json:
appsettings.json
Trong môi trường development, hãy lưu key bằng user secrets thay vì lưu trong appsettings.json:

Tài nguyên

NuGet Package

Phiên bản package và lệnh cài đặt.

GitHub Repository

Mã nguồn, các bản release và ví dụ.

API Reference

Mọi endpoint, parameter và response.

Discord Community

Đặt câu hỏi và trao đổi với các developer khác.

Hỗ trợ

Để được hỗ trợ về C# SDK:
Lần sửa đổi cuối 26 tháng 9, 2026