C# - Dodo Payments Documentation

C# SDK는 .NET 애플리케이션에 Dodo Payments REST API에 대한 유형이 지정된 액세스를 제공합니다. 모든 API 메서드는 비동기 방식이며 Task을 반환하고, requests와 responses는 유형이 지정된 클래스이며, client가 실패한 requests를 자동으로 재시도합니다.

설치

NuGet에서 패키지를 설치합니다:

dotnet add package DodoPayments.Client

SDK에는 .NET Standard 2.0 이상이 필요하며 .NET 8 빌드도 함께 제공됩니다. ASP.NET Core, console applications 및 기타 .NET project types에서 사용할 수 있습니다. 이 페이지의 예제에서는 collection expressions와 같은 C# 12 구문을 사용합니다.

빠른 시작

client를 생성한 다음 checkout session을 생성합니다:

using System;
using DodoPayments.Client;
using DodoPayments.Client.Models.CheckoutSessions;

// Configured using the DODO_PAYMENTS_API_KEY, DODO_PAYMENTS_WEBHOOK_KEY, and DODO_PAYMENTS_BASE_URL environment variables
DodoPaymentsClient client = new();

CheckoutSessionCreateParams parameters = new()
{
    ProductCart =
    [
        new()
        {
            ProductID = "pdt_123",
            Quantity = 1,
        },
    ],
};

var checkoutSessionResponse = await client.CheckoutSessions.Create(parameters);

Console.WriteLine(checkoutSessionResponse.SessionID);

BearerToken을 설정하지 않으면 client가 DODO_PAYMENTS_API_KEY environment variable을 읽습니다. BaseUrl 또는 DODO_PAYMENTS_BASE_URL을 설정하지 않으면 client가 live mode에 연결됩니다. test mode를 사용하려면 Environments를 참조하세요. test mode API key는 test mode에서만 작동합니다.

API keys는 environment variables, user secrets 또는 Azure Key Vault에 보관하세요. 소스 코드에 직접 작성하거나 version control에 commit하지 마세요.

핵심 기능

Async/Await

모든 API method는 Task을 반환하며 선택적 CancellationToken을 허용합니다.

Strong Typing

nullable reference type annotations가 포함된 유형이 지정된 request 및 response classes입니다.

Smart Retries

connection errors 및 retryable status codes에 대해 exponential backoff를 적용하여 기본적으로 두 번 재시도합니다.

Error Handling

일반적인 각 HTTP error status에 대한 exception class를 제공하며, status code와 response body를 포함합니다.

Configuration

Environment Variables

API key를 environment variable에 저장합니다:

.env

DODO_PAYMENTS_API_KEY=your_api_key_here

new()로 생성한 client는 설정을 environment에서 읽습니다:

// Automatically reads from environment variables
DodoPaymentsClient client = new();

일치하는 property를 설정하지 않으면 client가 다음 environment variables를 읽습니다:

Property	Environment variable	Required	Default value
`BearerToken`	`DODO_PAYMENTS_API_KEY`	true	-
`WebhookKey`	`DODO_PAYMENTS_WEBHOOK_KEY`	false	-
`BaseUrl`	`DODO_PAYMENTS_BASE_URL`	true	`"https://live.dodopayments.com"`

BearerToken와 DODO_PAYMENTS_API_KEY이 모두 설정되지 않으면 client가 DodoPaymentsInvalidDataException을 throw합니다. WebhookKey은 webhook signing secret을 저장하지만 C# SDK에는 webhook signatures를 검증하는 method가 없습니다. 검증하려면 Webhooks를 따르세요.

수동 Configuration

environment variables를 재정의하려면 client에서 properties를 설정합니다:

DodoPaymentsClient client = new() { BearerToken = "My Bearer Token" };

Environments

client는 기본적으로 live mode(https://live.dodopayments.com)에 연결됩니다. test mode(https://test.dodopayments.com)를 사용하려면 BaseUrl을 EnvironmentUrl.TestMode으로 설정합니다:

using DodoPayments.Client.Core;

DodoPaymentsClient client = new() { BaseUrl = EnvironmentUrl.TestMode };

재시도

SDK는 connection errors와 status 408, 409, 429 또는 500 이상의 responses를 재시도합니다. exponential backoff를 적용하여 기본적으로 두 번 재시도합니다. 재시도 횟수를 변경하려면 MaxRetries을 설정하고, 재시도를 끄려면 0으로 설정합니다:

// Custom retry count
DodoPaymentsClient client = new() { MaxRetries = 3 };

Timeouts

각 request 시도는 기본적으로 1분 후 timeout됩니다. timeout에는 retries가 포함되지 않습니다. 변경하려면 Timeout을 설정합니다:

DodoPaymentsClient client = new() { Timeout = TimeSpan.FromSeconds(30) };

Per-Request 재정의

단일 call의 설정을 변경하려면 client 또는 service에서 WithOptions을 호출합니다. 동일한 connection pool을 공유하는 수정된 copy를 반환하며 원래 client는 변경되지 않습니다:

var response = await client
    .WithOptions(options => options with
    {
        Timeout = TimeSpan.FromSeconds(10),
        MaxRetries = 5,
    })
    .CheckoutSessions.Create(parameters);

일반적인 Operations

이 section의 examples에서는 Quick Start의 client을 사용합니다.

Checkout Session 생성

checkout session을 생성한 다음 반환된 CheckoutUrl으로 customer를 redirect합니다:

var parameters = new CheckoutSessionCreateParams
{
    ProductCart =
    [
        new()
        {
            ProductID = "pdt_123",
            Quantity = 1
        }
    ],
    ReturnUrl = "https://yourdomain.com/return"
};

var session = await client.CheckoutSessions.Create(parameters);
Console.WriteLine($"Checkout URL: {session.CheckoutUrl}");

각 checkout URL은 한 번만 사용할 수 있으며 24시간 후 만료됩니다. 모든 session option은 Checkout Sessions을 참조하세요.

Customers 관리

email address와 name으로 customer를 생성한 다음 ID로 조회합니다:

using DodoPayments.Client.Models.Customers;

// Create a customer
var customer = await client.Customers.Create(new CustomerCreateParams
{
    Email = "customer@example.com",
    Name = "John Doe"
});

// Retrieve customer
var retrieved = await client.Customers.Retrieve(new CustomerRetrieveParams { CustomerID = "cus_123" });
Console.WriteLine($"Customer: {retrieved.Name} ({retrieved.Email})");

Customers.Retrieve은 ID를 string으로도 허용합니다. 예: client.Customers.Retrieve("cus_123").

Subscriptions 처리

subscription을 생성한 다음 on-demand subscription인 경우 charge합니다.

POST /subscriptions(SDK의 Subscriptions.Create method)은 deprecated입니다. 기존 integrations에서는 계속 작동하지만 새 integrations에서는 Checkout Session을 통해 subscriptions를 생성해야 합니다.

using DodoPayments.Client.Models.Payments;
using DodoPayments.Client.Models.Subscriptions;

// Create a subscription
var subscription = await client.Subscriptions.Create(new SubscriptionCreateParams
{
    Billing = new BillingAddress
    {
        Country = "US",
        City = "San Francisco",
        State = "CA",
        Street = "1 Market St",
        Zipcode = "94105",
    },
    Customer = new AttachExistingCustomer { CustomerID = "cus_123" },
    ProductID = "pdt_456",
    Quantity = 1,
});

// Charge an on-demand subscription
// ProductPrice is in the lowest currency denomination (e.g., 2500 = $25.00 USD)
var charge = await client.Subscriptions.Charge(new SubscriptionChargeParams
{
    SubscriptionID = subscription.SubscriptionID,
    ProductPrice = 2500,
});

Billing에는 Country(두 글자의 ISO country code)만 필요합니다. Customer에는 기존 customer를 연결하기 위한 AttachExistingCustomer 또는 customer를 생성하기 위한 NewCustomer을 전달합니다. Charge은 on-demand subscriptions에 사용하며, ProductPrice은 통화의 최소 단위입니다.

Error Handling

API가 error status를 반환하면 SDK는 DodoPaymentsApiException의 subclass를 throw합니다. 이 subclass에는 StatusCode 및 ResponseBody properties가 있습니다. exception class는 status code에 따라 결정됩니다. 모든 4xx exceptions는 DodoPayments4xxException을 상속합니다.

Status	Exception
400	`DodoPaymentsBadRequestException`
401	`DodoPaymentsUnauthorizedException`
403	`DodoPaymentsForbiddenException`
404	`DodoPaymentsNotFoundException`
422	`DodoPaymentsUnprocessableEntityException`
429	`DodoPaymentsRateLimitException`
5xx	`DodoPayments5xxException`
others	`DodoPaymentsUnexpectedStatusCodeException`

409와 같이 자체 class가 없는 4xx status는 DodoPayments4xxException을 throw합니다. DodoPaymentsUnexpectedStatusCodeException은 4xx 및 5xx 범위 밖의 statuses를 처리합니다. SDK는 다음 exceptions도 throw합니다:

DodoPaymentsIOException: I/O 또는 network error입니다.
DodoPaymentsInvalidDataException: 예를 들어 required property가 누락되어 SDK가 response data를 해석할 수 없습니다.
DodoPaymentsException: 모든 SDK exception의 base class입니다.

Pagination

List methods는 결과의 한 page를 반환합니다. 모든 item을 반복 처리하거나 직접 pages를 이동할 수 있습니다.

자동 Pagination

Paginate은 필요할 때 다음 page를 가져오는 IAsyncEnumerable을 반환합니다:

var page = await client.Payments.List();
await foreach (var item in page.Paginate())
{
    Console.WriteLine(item);
}

수동 Pagination

한 번에 하나의 page를 처리하려면 Items을 읽은 다음 HasNext() 및 Next()을 호출합니다:

var page = await client.Payments.List();
while (true)
{
    foreach (var item in page.Items)
    {
        Console.WriteLine(item);
    }
    if (!page.HasNext())
    {
        break;
    }
    page = await page.Next();
}

page size를 설정하려면 DodoPayments.Client.Models.Payments namespace의 PaymentListParams을 전달합니다. 예: client.Payments.List(new PaymentListParams { PageSize = 50 }).

ASP.NET Core Integration

dependency injection container에 하나의 client를 singleton으로 등록하고 configuration에서 API key를 읽습니다:

Program.cs

using DodoPayments.Client;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddSingleton<DodoPaymentsClient>(sp =>
{
    var configuration = sp.GetRequiredService<IConfiguration>();
    return new DodoPaymentsClient
    {
        BearerToken = configuration["DodoPayments:ApiKey"]
    };
});

var app = builder.Build();
app.Run();

configuration에 key를 추가합니다. 예를 들어 appsettings.json에 추가할 수 있습니다:

appsettings.json

{
  "DodoPayments": {
    "ApiKey": "your_api_key_here"
  }
}

development 환경에서는 appsettings.json 대신 user secrets에 key를 저장합니다:

dotnet user-secrets init
dotnet user-secrets set "DodoPayments:ApiKey" "your_api_key_here"

Resources

NuGet Package

Package versions 및 install commands입니다.

GitHub Repository

Source code, releases 및 examples입니다.

API Reference

모든 endpoint, parameter 및 response입니다.

Discord Community

질문하고 다른 developers와 소통하세요.

Support

C# SDK에 대한 도움이 필요하면 다음을 이용하세요:

Discord: 실시간 도움을 받으려면 community server에 참여하세요.
Email: support@dodopayments.com으로 문의하세요.
GitHub: repository에 issue를 등록하세요.

Getting Started

Features

Integrate

Merchant of Record

Miscellaneous

C#

설치

빠른 시작

핵심 기능

Async/Await

Strong Typing

Smart Retries

Error Handling

Configuration

Environment Variables

수동 Configuration

Environments

재시도

Timeouts

Per-Request 재정의

일반적인 Operations

Checkout Session 생성

Customers 관리

Subscriptions 처리

Error Handling

ASP.NET Core Integration

Resources

NuGet Package

GitHub Repository

API Reference

Discord Community

Support

​설치

​빠른 시작

​핵심 기능

Async/Await

Strong Typing

Smart Retries

Error Handling

​Configuration

​Environment Variables

​수동 Configuration

​Environments

​재시도

​Timeouts

​Per-Request 재정의

​일반적인 Operations

​Checkout Session 생성

​Customers 관리

​Subscriptions 처리

​Error Handling

​Pagination

​자동 Pagination

​수동 Pagination

​ASP.NET Core Integration

​Resources

NuGet Package

GitHub Repository

API Reference

Discord Community

​Support

설치

빠른 시작

핵심 기능

Configuration

Environment Variables

수동 Configuration

Environments

재시도

Timeouts

Per-Request 재정의

일반적인 Operations

Checkout Session 생성

Customers 관리

Subscriptions 처리

Error Handling

Pagination

자동 Pagination

수동 Pagination

ASP.NET Core Integration

Resources

Support