支付 - Dodo Payments Documentation

billing

object

必填

Billing address details for payments

Show child attributes

brand_id

string

必填

brand id this payment belongs to

business_id

string

必填

Identifier of the business associated with the payment

created_at

string<date-time>

必填

Timestamp when the payment was created

currency

enum<string>

必填

Currency used for the payment

可用选项:

AED,

ALL,

AMD,

ANG,

AOA,

ARS,

AUD,

AWG,

AZN,

BAM,

BBD,

BDT,

BGN,

BHD,

BIF,

BMD,

BND,

BOB,

BRL,

BSD,

BWP,

BYN,

BZD,

CAD,

CHF,

CLP,

CNY,

COP,

CRC,

CUP,

CVE,

CZK,

DJF,

DKK,

DOP,

DZD,

EGP,

ETB,

EUR,

FJD,

FKP,

GBP,

GEL,

GHS,

GIP,

GMD,

GNF,

GTQ,

GYD,

HKD,

HNL,

HRK,

HTG,

HUF,

IDR,

ILS,

INR,

IQD,

JMD,

JOD,

JPY,

KES,

KGS,

KHR,

KMF,

KRW,

KWD,

KYD,

KZT,

LAK,

LBP,

LKR,

LRD,

LSL,

LYD,

MAD,

MDL,

MGA,

MKD,

MMK,

MNT,

MOP,

MRU,

MUR,

MVR,

MWK,

MXN,

MYR,

MZN,

NAD,

NGN,

NIO,

NOK,

NPR,

NZD,

OMR,

PAB,

PEN,

PGK,

PHP,

PKR,

PLN,

PYG,

QAR,

RON,

RSD,

RUB,

RWF,

SAR,

SBD,

SCR,

SEK,

SGD,

SHP,

SLE,

SLL,

SOS,

SRD,

SSP,

STN,

SVC,

SZL,

THB,

TND,

TOP,

TRY,

TTD,

TWD,

TZS,

UAH,

UGX,

USD,

UYU,

UZS,

VES,

VND,

VUV,

WST,

XAF,

XCD,

XOF,

XPF,

YER,

ZAR,

ZMW

customer

object

必填

Details about the customer who made the payment

Show child attributes

digital_products_delivered

boolean

必填

Whether the digital products purchased in this payment have been delivered.

disputes

object[]

必填

List of disputes associated with this payment

Show child attributes

includes_usage

boolean

必填

True when this payment also bills metered usage or credit overage. The usage is for the billing cycle before the service period, not for the service period. The value is set for each payment status. It is false when charge_type is null.

is_multi_subscription

boolean

必填

True when one payment starts more than one subscription. Read this field to find the payment type. Do not read the length of subscription_ids. Do not read subscription_id for null.

is_update_payment_method

boolean

必填

Whether this payment was created solely to update a subscription's payment method (a zero-/setup-amount charge). false for normal charges.

metadata

Metadata · object

必填

Additional custom data associated with the payment

Show child attributes

payment_id

string

必填

Unique identifier for the payment

payment_provider

enum<string>

必填

Which processor handled this payment. stripe / adyen for BYOP routes (the merchant's own payment connector); dodo for everything Dodo processed itself.

可用选项:

stripe,

adyen,

dodo

refunds

object[]

必填

List of refunds issued for this payment

Show child attributes

retry_attempt

integer<int32>

必填

Retry attempt number for subscription renewal payments. 0 for the original payment, 1+ for each scheduled off-session retry after a failed renewal. Always 0 for non-subscription payments.

service_periods

object[]

必填

The service period of each subscription that this payment pays for. The order is the same as subscription_ids. For a plan change charge, the period starts at the plan change and ends at the next billing date. The list is empty unless the payment status is succeeded. The list is also empty for a one-time payment, an on-demand charge, or a payment method update. The list is set for new, renewal and plan_change charges that succeeded. It can be empty for some zero-amount payments. A renewal with no entry for its subscription bills usage only. That payment does not extend the service period.

Show child attributes

settlement_amount

integer<int32>

必填

The amount that will be credited to your Dodo balance after currency conversion and processing. Especially relevant for adaptive pricing where the customer's payment currency differs from your settlement currency.

settlement_currency

enum<string>

必填

The currency in which the settlement_amount will be credited to your Dodo balance. This may differ from the customer's payment currency in adaptive pricing scenarios.

可用选项:

AED,

ALL,

AMD,

ANG,

AOA,

ARS,

AUD,

AWG,

AZN,

BAM,

BBD,

BDT,

BGN,

BHD,

BIF,

BMD,

BND,

BOB,

BRL,

BSD,

BWP,

BYN,

BZD,

CAD,

CHF,

CLP,

CNY,

COP,

CRC,

CUP,

CVE,

CZK,

DJF,

DKK,

DOP,

DZD,

EGP,

ETB,

EUR,

FJD,

FKP,

GBP,

GEL,

GHS,

GIP,

GMD,

GNF,

GTQ,

GYD,

HKD,

HNL,

HRK,

HTG,

HUF,

IDR,

ILS,

INR,

IQD,

JMD,

JOD,

JPY,

KES,

KGS,

KHR,

KMF,

KRW,

KWD,

KYD,

KZT,

LAK,

LBP,

LKR,

LRD,

LSL,

LYD,

MAD,

MDL,

MGA,

MKD,

MMK,

MNT,

MOP,

MRU,

MUR,

MVR,

MWK,

MXN,

MYR,

MZN,

NAD,

NGN,

NIO,

NOK,

NPR,

NZD,

OMR,

PAB,

PEN,

PGK,

PHP,

PKR,

PLN,

PYG,

QAR,

RON,

RSD,

RUB,

RWF,

SAR,

SBD,

SCR,

SEK,

SGD,

SHP,

SLE,

SLL,

SOS,

SRD,

SSP,

STN,

SVC,

SZL,

THB,

TND,

TOP,

TRY,

TTD,

TWD,

TZS,

UAH,

UGX,

USD,

UYU,

UZS,

VES,

VND,

VUV,

WST,

XAF,

XCD,

XOF,

XPF,

YER,

ZAR,

ZMW

subscription_ids

string[]

必填

Every subscription that this payment starts or charges, in a stable order. It is empty for a one-time payment. It holds the value of subscription_id when the payment names one subscription.

total_amount

integer<int32>

必填

Total amount charged to the customer including tax, in the currency's smallest unit (e.g. cents for USD, yen for JPY, fils for KWD — see the currency's decimal places)

card_exp_month

string | null

Expiry month of the card, as two digits from 01 to 12. For Apple Pay and Google Pay, this is the expiry of the wallet token, which can differ from the expiry of the physical card.

card_exp_year

string | null

Expiry year of the card, as four digits, for example 2029. For Apple Pay and Google Pay, this is the expiry of the wallet token, which can differ from the expiry of the physical card.

card_holder_name

string | null

Cardholder name

card_issuing_country

null | enum<string>

ISO2 country code of the card

可用选项:

AF,

AX,

AL,

DZ,

AS,

AD,

AO,

AI,

AQ,

AG,

AR,

AM,

AW,

AU,

AT,

AZ,

BS,

BH,

BD,

BB,

BY,

BE,

BZ,

BJ,

BM,

BT,

BO,

BQ,

BA,

BW,

BV,

BR,

IO,

BN,

BG,

BF,

BI,

KH,

CM,

CA,

CV,

KY,

CF,

TD,

CL,

CN,

CX,

CC,

CO,

KM,

CG,

CD,

CK,

CR,

CI,

HR,

CU,

CW,

CY,

CZ,

DK,

DJ,

DM,

DO,

EC,

EG,

SV,

GQ,

ER,

EE,

ET,

FK,

FO,

FJ,

FI,

FR,

GF,

PF,

TF,

GA,

GM,

GE,

DE,

GH,

GI,

GR,

GL,

GD,

GP,

GU,

GT,

GG,

GN,

GW,

GY,

HT,

HM,

VA,

HN,

HK,

HU,

IS,

IN,

ID,

IR,

IQ,

IE,

IM,

IL,

IT,

JM,

JP,

JE,

JO,

KZ,

KE,

KI,

KP,

KR,

KW,

KG,

LA,

LV,

LB,

LS,

LR,

LY,

LI,

LT,

LU,

MO,

MK,

MG,

MW,

MY,

MV,

ML,

MT,

MH,

MQ,

MR,

MU,

YT,

MX,

FM,

MD,

MC,

MN,

ME,

MS,

MA,

MZ,

MM,

NA,

NR,

NP,

NL,

NC,

NZ,

NI,

NE,

NG,

NU,

NF,

MP,

NO,

OM,

PK,

PW,

PS,

PA,

PG,

PY,

PE,

PH,

PN,

PL,

PT,

PR,

QA,

RE,

RO,

RU,

RW,

BL,

SH,

KN,

LC,

MF,

PM,

VC,

WS,

SM,

ST,

SA,

SN,

RS,

SC,

SL,

SG,

SX,

SK,

SI,

SB,

SO,

ZA,

GS,

SS,

ES,

LK,

SD,

SR,

SJ,

SZ,

SE,

CH,

SY,

TW,

TJ,

TZ,

TH,

TL,

TG,

TK,

TO,

TT,

TN,

TR,

TM,

TC,

TV,

UG,

UA,

AE,

GB,

UM,

US,

UY,

UZ,

VU,

VE,

VN,

VG,

VI,

WF,

EH,

YE,

ZM,

ZW

card_last_four

string | null

The last four digits of the card

card_network

string | null

Card network, in lowercase, for example visa, mastercard or amex. Older payments can carry other casing.

card_type

string | null

The type of card, in lowercase: credit, debit or prepaid. Older payments can carry other casing.

charge_type

null | enum<string>

The type of subscription charge that this payment is for. Refer to ChargeType. The value is set for each payment status, not only for succeeded. The value is null when this payment charges no subscription.

可用选项:

new,

renewal,

plan_change,

on_demand

checkout_session_id

string | null

If payment is made using a checkout session, this field is set to the id of the session.

custom_field_responses

object[] | null

Customer's responses to custom fields collected during checkout

Show child attributes

discount_id

string | null

已弃用

DEPRECATED: Use discounts instead. Returns the first discount's ID if present.

discounts

object[] | null

All stacked discounts applied, ordered by position

Show child attributes

error_code

string | null

An error code if the payment failed

error_message

string | null

An error message if the payment failed. When error_code is a recognised unified code, this is the merchant-facing headline + recommended action (Payment Details copy) rather than the raw connector text.

invoice_id

string | null

Invoice ID for this payment. Uses India-specific invoice ID if available.

invoice_url

string | null

已弃用

DEPRECATED: Use GET /invoices/payments/{payment_id} with an API key. URL to download the invoice PDF for this payment. The URL has no signed token. If the business asks for a credential on its invoice links, the URL needs an API key.

payment_link

string | null

Checkout URL

payment_method

string | null

Payment method used by customer (e.g. "card", "bank_transfer")

payment_method_id

string | null

Identifier of the saved payment method used for this payment, if any.

payment_method_type

string | null

Specific type of payment method (e.g. "visa", "mastercard")

product_cart

One-Time Product Cart Item Response · object[] | null

List of products purchased in a one-time payment

Show child attributes

refund_status

null | enum<string>

Summary of the refund status for this payment. None if no succeeded refunds exist.

可用选项:

partial,

full

settlement_tax

integer<int32> | null

This represents the portion of settlement_amount that corresponds to taxes collected. Especially relevant for adaptive pricing where the tax component must be tracked separately in your Dodo balance.

status

null | enum<string>

Current status of the payment intent

可用选项:

succeeded,

failed,

cancelled,

processing,

requires_customer_action,

requires_merchant_action,

requires_payment_method,

requires_confirmation,

requires_capture,

partially_captured,

partially_captured_and_capturable

subscription_id

string | null

Identifier of the subscription if payment is part of a subscription. A multi-subscription payment leaves this null, because no single subscription owns the payment. Read subscription_ids for those.

tax

integer<int32> | null

Amount of tax collected in the currency's smallest unit (e.g. cents for USD, yen for JPY, fils for KWD)

updated_at

string<date-time> | null

Timestamp when the payment was last updated

最后修改于 2026年6月9日

{
  "billing": {
    "city": "<string>",
    "state": "<string>",
    "street": "<string>",
    "zipcode": "<string>"
  },
  "brand_id": "<string>",
  "business_id": "<string>",
  "created_at": "2023-11-07T05:31:56Z",
  "customer": {
    "customer_id": "<string>",
    "email": "<string>",
    "name": "<string>",
    "metadata": {},
    "phone_number": "<string>"
  },
  "digital_products_delivered": true,
  "disputes": [
    {
      "amount": "<string>",
      "business_id": "<string>",
      "created_at": "2023-11-07T05:31:56Z",
      "currency": "<string>",
      "dispute_id": "<string>",
      "payment_id": "<string>",
      "is_resolved_by_rdr": true,
      "remarks": "<string>"
    }
  ],
  "includes_usage": true,
  "is_multi_subscription": true,
  "is_update_payment_method": true,
  "metadata": {},
  "payment_id": "<string>",
  "refunds": [
    {
      "business_id": "<string>",
      "created_at": "2023-11-07T05:31:56Z",
      "is_partial": true,
      "payment_id": "<string>",
      "refund_id": "<string>",
      "amount": 123,
      "network_reference": "<string>",
      "network_reference_updated_at": "2023-11-07T05:31:56Z",
      "reason": "<string>"
    }
  ],
  "retry_attempt": 123,
  "service_periods": [
    {
      "ends_at": "2023-11-07T05:31:56Z",
      "proration_factor": "1",
      "starts_at": "2023-11-07T05:31:56Z",
      "subscription_id": "<string>"
    }
  ],
  "settlement_amount": 123,
  "subscription_ids": [
    "<string>"
  ],
  "total_amount": 123,
  "card_exp_month": "<string>",
  "card_exp_year": "<string>",
  "card_holder_name": "<string>",
  "card_last_four": "<string>",
  "card_network": "<string>",
  "card_type": "<string>",
  "checkout_session_id": "<string>",
  "custom_field_responses": [
    {
      "key": "<string>",
      "value": "<string>"
    }
  ],
  "discount_id": "<string>",
  "discounts": [
    {
      "amount": 123,
      "business_id": "<string>",
      "code": "<string>",
      "created_at": "2023-11-07T05:31:56Z",
      "discount_id": "<string>",
      "metadata": {},
      "position": 123,
      "preserve_on_plan_change": true,
      "restricted_to": [
        "<string>"
      ],
      "times_used": 123,
      "cycles_remaining": 123,
      "expires_at": "2023-11-07T05:31:56Z",
      "name": "<string>",
      "subscription_cycles": 123,
      "usage_limit": 123
    }
  ],
  "error_code": "<string>",
  "error_message": "<string>",
  "invoice_id": "<string>",
  "invoice_url": "<string>",
  "payment_link": "<string>",
  "payment_method": "<string>",
  "payment_method_id": "<string>",
  "payment_method_type": "<string>",
  "product_cart": [
    {
      "product_id": "<string>",
      "quantity": 1
    }
  ],
  "settlement_tax": 123,
  "subscription_id": "<string>",
  "tax": 123,
  "updated_at": "2023-11-07T05:31:56Z"
}

Getting Started

Features

Integrate

Merchant of Record

Miscellaneous

支付