Create an Off Session Payment v2

Core Resources

Off Session Payments

Create an Off Session Payment

Creates an OffSessionPayment object.

Learn more about calling API v2 endpoints.

Parameters

amountobjectRequired
The “presentment amount” to be collected from the customer.
- amount.currencyenumRequired
  Three-letter ISO currency code, in lowercase. Must be a supported currency.
- amount.valueintegerRequired
  A non-negative integer representing how much to charge in the smallest currency unit.

cadenceenumRequired
The frequency of the underlying payment.
Possible enum values
recurring
Indicates a transaction occurring on a regular interval.
unscheduled
Indicates a transaction occurring at irregular periods.

customerstringRequired
ID of the Customer to which this OffSessionPayment belongs.

metadatamapRequired
Set of key-value pairs that you can attach to an object. This can be useful for storing additional information about the object in a structured format. Learn more about storing information in metadata.

payment_methodstringRequired
ID of the payment method used in this OffSessionPayment.

on_behalf_ofstring
The account (if any) for which the funds of the OffSessionPayment are intended.

payment_method_optionsobject
Payment method options for the off-session payment.
- payment_method_options.cardobject
  Payment method options for the card payment type.

retry_detailsobject
Details about the OffSessionPayment retries.
- retry_details.retry_policystring
  The pre-configured retry policy to use for the payment.
- retry_details.retry_strategyenum
  Indicates the strategy for how you want Stripe to retry the payment.
  Possible enum values
  best_available
  Indicates that you want Stripe to retry the payment automatically via the best available strategy.
  none
  Indicates that you don’t want Stripe to retry the payment.

statement_descriptorstring
Text that appears on the customer’s statement as the statement descriptor for a non-card charge. This value overrides the account’s default statement descriptor. For information about requirements, including the 22-character limit, see the Statement Descriptor docs.

statement_descriptor_suffixstring
Provides information about a card charge. Concatenated to the account’s statement descriptor prefix to form the complete statement descriptor that appears on the customer’s statement.

test_clockstring
Test clock that can be used to advance the retry attempts in a sandbox.

transfer_dataobject
The data that automatically creates a Transfer after the payment finalizes. Learn more about the use case for connected accounts.
- transfer_data.destinationstringRequired
  The account (if any) that the payment is attributed to for tax reporting, and where funds from the payment are transferred to after payment success.
- transfer_data.amountinteger
  The amount transferred to the destination account. This transfer will occur automatically after the payment succeeds. If no amount is specified, by default the entire payment amount is transferred to the destination account. The amount must be less than or equal to the amount_requested, and must be a positive integer representing how much to transfer in the smallest currency unit (e.g., 100 cents to charge $1.00).

Returns

Response attributes

idstring
Unique identifier for the object.

objectstring, value is "v2.payments.off_session_payment"
String representing the object’s type. Objects of the same type share the same value of the object field.

amount_requestedobject
The “presentment amount” to be collected from the customer.
- amount_requested.currencyenum
  Three-letter ISO currency code, in lowercase. Must be a supported currency.
- amount_requested.valueinteger
  A non-negative integer representing how much to charge in the smallest currency unit.

cadenceenum
The frequency of the underlying payment.
Possible enum values
recurring
Indicates a transaction occurring on a regular interval.
unscheduled
Indicates a transaction occurring at irregular periods.

compartment_idstring
ID of the owning compartment.

createdtimestamp
Creation time of the OffSessionPayment. Represented as a RFC 3339 date & time UTC value in millisecond precision, for example: 2022-09-18T13:22:18.123Z.

customerstring
ID of the Customer to which this OffSessionPayment belongs.

failure_reasonnullable enum

The reason why the OffSessionPayment failed.

Possible enum values

authorization_expired

The payment failed because the authorization expired.

rejected_by_partner

The payment failed because the payment partner returned a terminal failure.

retries_exhausted

The payment failed because we ran out of retry attempts.

last_authorization_attempt_errornullable string
The payment error encountered in the previous attempt to authorize the payment.

latest_payment_attempt_recordnullable string
Payment attempt record for the latest attempt, if one exists.

livemodeboolean
Has the value true if the object exists in live mode or the value false if the object exists in test mode.

metadatamap
Set of key-value pairs that you can attach to an object. This can be useful for storing additional information about the object in a structured format. Learn more about storing information in metadata.

on_behalf_ofnullable string
The account (if any) for which the funds of the OffSessionPayment are intended.

payment_methodstring
ID of the payment method used in this OffSessionPayment.

payment_recordnullable string
Payment record associated with the OffSessionPayment.

payments_orchestrationobject
Details about the payments orchestration configuration.
- payments_orchestration.enabledboolean
  True when you want to enable payments orchestration for this off-session payment. False otherwise.

retry_detailsobject

Details about the OffSessionPayment retries.

retry_details.attemptsinteger
Number of authorization attempts so far.

retry_details.retry_policynullable string
The pre-configured retry policy to use for the payment.

retry_details.retry_strategyenum

Indicates the strategy for how you want Stripe to retry the payment.

Possible enum values

heuristic

Indicates that you want Stripe to retry the payment automatically via pre-determined heuristics.

none

Indicates that you don’t want Stripe to retry the payment.

scheduled

Indicates that you want Stripe to retry the payment automatically on a fixed schedule.

smart

Indicates that you want Stripe to retry the payment automatically via ML predictions.

statement_descriptornullable string
Text that appears on the customer’s statement as the statement descriptor for a non-card charge. This value overrides the account’s default statement descriptor. For information about requirements, including the 22-character limit, see the Statement Descriptor docs.

statement_descriptor_suffixnullable string
Provides information about a card charge. Concatenated to the account’s statement descriptor prefix to form the complete statement descriptor that appears on the customer’s statement.

statusenum

Status of this OffSessionPayment, one of pending, pending_retry, processing, failed, canceled, requires_capture, or succeeded.

Possible enum values

canceled

The payment was manually canceled.

failed

The payment is terminally failed.

pending

Payment has not yet been attempted.

pending_retry

The payment failed a previous attempt and will be retried automatically.

processing

The payment is currently processing an authorization attempt. Any manual operations on it will be blocked.

requires_capture

The payment is awaiting capture.

succeeded

The payment has successfully moved money.

test_clocknullable string
Test clock that can be used to advance the retry attempts in a sandbox.

transfer_datanullable object
The data that automatically creates a Transfer after the payment finalizes. Learn more about the use case for connected accounts.
- transfer_data.amountnullable integer
  The amount transferred to the destination account. This transfer will occur automatically after the payment succeeds. If no amount is specified, by default the entire payment amount is transferred to the destination account. The amount must be less than or equal to the amount_requested, and must be a positive integer representing how much to transfer in the smallest currency unit (e.g., 100 cents to charge $1.00).
- transfer_data.destinationstring
  The account (if any) that the payment is attributed to for tax reporting, and where funds from the payment are transferred to after payment success.

Error Codes

400off_session_payment_heuristic_retries_not_supported_for_cards

Card payment methods do not support heuristic retries.

400off_session_payment_incorrect_payment_method_type_for_options

You may not provide payment method options that do not match the payment method type.

400off_session_payment_retry_policy_not_supported_for_debit_payment_methods

Debit payment methods do not support custom retry policies.

400off_session_payment_retry_policy_strategy_mutually_exclusive

You may not specify both a retry_policy and retry_strategy. These parameters are mutually exclusive.

400off_session_payment_smart_retries_not_supported_for_debit_payment_methods

Debit payment methods do not support smart retries.

400off_session_payment_test_clock_in_livemode

Test clocks may not be used with the Off-Session Payments API in livemode. Please use your sandbox keys to test with test clocks.

400osp_ach_retries_not_enabled

To schedule ACH payment retries with the Off-Session Payments API, you must first enable ACH retries on the Stripe dashboard.

400osp_amount_too_large

The Off-Session Payments API has limits on the maximum amount you may charge in each currency.

400osp_amount_too_small

The Off-Session Payments API has limits on the minimum amount you may charge in each currency.

400osp_generic_invalid_request

A generic error occurred during payment. See error message for more details.

400osp_invalid_payment_method_type

Indicates that the payment method you provided is not compatible with the Off-Session Payments API. The Off-Session Payments API currently only supports card payment methods, including ones generated from wallets.

400osp_payment_method_not_attached

To use the Off-Session Payments API, you must first attach the PaymentMethod to the Customer via the Setup Intents API.

400osp_payments_orchestration_not_supported_with_connect

Payments orchestration is not supported with connect integrations.

400osp_payments_orchestration_not_supported_with_smart_retries

Smart retries are not supported for orchestrated OSPS at this time.

400osp_payments_orchestration_only_supported_for_cards

Payments orchestration is currently only supported for card payment method types.

400osp_pm_not_setup_for_off_session

To use the Off-Session Payments API, you must first set up the PaymentMethod for off-session usage via the Setup Intents API.

400osp_pm_set_up_only_on_connected_account

To use the Off-Session Payments API, you must first set up the PaymentMethod for off-session usage via the Setup Intents API. You must use the same value for on_behalf_of when calling into the SetupIntent API as what you use in the Off-Session Payments API.

400osp_pm_set_up_only_on_platform

400osp_sepa_debit_retries_not_enabled

To schedule SEPA Debit payment retries with the Off-Session Payments API, you must first enable SEPA Debit retries on the Stripe dashboard.

POST /v2/payments/off_session_payments

cURL

curl -X POST https://api.stripe.com/v2/payments/off_session_payments \
  -H "Authorization: Bearer sk_test_BQokikJ...2HlWgH4olfQ2sk_test_BQokikJOvBiI2HlWgH4olfQ2" \
  -H "Stripe-Version: 2026-01-28.preview" \
  --json '{
    "amount": {
        "value": 2000,
        "currency": "usd"
    },
    "retry_details": {
        "retry_strategy": "smart"
    },
    "cadence": "recurring",
    "customer": "cus_SJjFsJvGPQKfH1",
    "payment_method": "pm_1RP6TAG7mvlzf7RNfspLoGQ9",
    "metadata": {}
  }'

Response

{
  "amount_requested": {
    "value": 2000,
    "currency": "usd"
  },
  "cadence": "recurring",
  "compartment_id": "wksp_test_6OdsB30MSQB61rhH1uYqVKa",
  "created": "2025-01-01T00:00:00.000Z",
  "customer": "cus_SJjFsJvGPQKfH1",
  "failure_reason": null,
  "id": "osp_test_6pO5OrRN03IzV8rd3BaY",
  "last_authorization_attempt_error": null,
  "latest_payment_attempt_record": null,
  "livemode": false,
  "metadata": {},
  "object": "v2.payments.off_session_payment",
  "on_behalf_of": null,
  "payment_method": "pm_1RP6TAG7mvlzf7RNfspLoGQ9",
  "payment_record": null,
  "payments_orchestration": null,
  "retry_details": {
    "attempts": 0,
    "retry_strategy": "smart"
  },
  "statement_descriptor": null,
  "statement_descriptor_suffix": null,
  "status": "pending",
  "test_clock": null,
  "transfer_data": null
}

Create an Off Session Payment v2

Parameters

amountobjectRequired

amount.currencyenumRequired

amount.valueintegerRequired

cadenceenumRequired

customerstringRequired

metadatamapRequired

payment_methodstringRequired

on_behalf_ofstring

payment_method_optionsobject

payment_method_options.cardobject

retry_detailsobject

retry_details.retry_policystring

retry_details.retry_strategyenum

statement_descriptorstring

statement_descriptor_suffixstring

test_clockstring

transfer_dataobject

transfer_data.destinationstringRequired

transfer_data.amountinteger

Returns

Response attributes

idstring

objectstring, value is "v2.payments.off_session_payment"

amount_requestedobject

amount_requested.currencyenum

amount_requested.valueinteger

cadenceenum

compartment_idstring

createdtimestamp

customerstring

failure_reasonnullable enum

last_authorization_attempt_errornullable string

latest_payment_attempt_recordnullable string

livemodeboolean

metadatamap

on_behalf_ofnullable string

payment_methodstring

payment_recordnullable string

payments_orchestrationobject

payments_orchestration.enabledboolean

retry_detailsobject

retry_details.attemptsinteger

retry_details.retry_policynullable string

retry_details.retry_strategyenum

statement_descriptornullable string

statement_descriptor_suffixnullable string

statusenum

test_clocknullable string

transfer_datanullable object

transfer_data.amountnullable integer

transfer_data.destinationstring