Create an OutboundPayment object v2

Money Management

Outbound Payments

Create an OutboundPayment object

Creates an OutboundPayment.

Learn more about calling API v2 endpoints.

Parameters

amountobjectRequired
The “presentment amount” to be sent to the recipient.
- amount.currencystringRequired
  A lowercase alpha3 currency code like “usd”.
- amount.valueintegerRequired
  In minor units like 123 for 1.23 USD.

fromobjectRequired
From which FinancialAccount and BalanceType to pull funds from.
- from.currencystringRequired
  Describes the FinancialAmount’s currency drawn from.
- from.financial_accountstringRequired
  The FinancialAccount that funds were pulled from.

toobjectRequired
To which payout method to send the OutboundPayment.
- to.currencystring
  Describes the currency to send to the recipient. If included, this currency must match a currency supported by the destination. Can be omitted in the following cases:
  destination only supports one currency
  destination supports multiple currencies and one of the currencies matches the FA currency
  destination supports multiple currencies and one of the currencies matches the presentment currency Note - when both FA currency and presentment currency are supported, we pick the FA currency to minimize FX.
- to.payout_methodstring
  The payout method which the OutboundPayment uses to send payout.
- to.recipientstringRequired
  To which account the OutboundPayment is sent.

delivery_optionsobject
Delivery options to be used to send the OutboundPayment.
- delivery_options.bank_accountenum
  Method for bank account.
  Possible enum values
  automatic
  Method automatically selected by Stripe.
  local
  The group of local bank-transfer networks in the bank account’s country.
  wire
  The group of wire transfer networks in the bank account’s country.

descriptionstring
An arbitrary string attached to the OutboundPayment. Often useful for displaying to users.

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.

outbound_payment_quotestringPreview feature
The quote for this OutboundPayment. Only required for countries with regulatory mandates to display fee estimates before OutboundPayment creation.

recipient_notificationobject
Details about the notification settings for the OutboundPayment recipient.
- recipient_notification.settingenumRequired
  Configuration option to enable or disable notifications to recipients. Do not send notifications when setting is NONE. Default to account setting when setting is CONFIGURED or not set.
  Possible enum values
  configured
  Default to account setting.
  none
  Do not send email.

Returns

Response attributes

idstring
Unique identifier for the OutboundPayment.

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

amountobject
The “presentment amount” for the OutboundPayment.
- amount.currencystring
  A lowercase alpha3 currency code like “usd”.
- amount.valueinteger
  In minor units like 123 for 1.23 USD.

cancelableboolean
Returns true if the OutboundPayment can be canceled, and false otherwise.

createdtimestamp
Time at which the OutboundPayment was created. Represented as a RFC 3339 date & time UTC value in millisecond precision, for example: 2022-09-18T13:22:18.123Z.

delivery_optionsnullable object
Delivery options to be used to send the OutboundPayment.
- delivery_options.bank_accountnullable enum
  Method for bank account.
  Possible enum values
  automatic
  Method automatically selected by Stripe.
  local
  The group of local bank-transfer networks in the bank account’s country.
  wire
  The group of wire transfer networks in the bank account’s country.

descriptionnullable string
An arbitrary string attached to the OutboundPayment. Often useful for displaying to users.

expected_arrival_datenullable timestamp
The date when funds are expected to arrive in the payout method. This field is not set if the payout method is in a failed, canceled, or returned state. Represented as a RFC 3339 date & time UTC value in millisecond precision, for example: 2022-09-18T13:22:18.123Z.

fromobject
The FinancialAccount that funds were pulled from.
- from.debitedobject
  The monetary amount debited from the sender, only set on responses.
  from.debited.currencystring
  A lowercase alpha3 currency code like “usd”.
  from.debited.valueinteger
  In minor units like 123 for 1.23 USD.
- from.financial_accountstring
  The FinancialAccount that funds were pulled from.

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

metadatanullable map
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.

outbound_payment_quotenullable stringPreview feature
The quote for this OutboundPayment. Only required for countries with regulatory mandates to display fee estimates before OutboundPayment creation.

receipt_urlnullable string
A link to the Stripe-hosted receipt for this OutboundPayment. The receipt link remains active for 60 days from the OutboundPayment creation date. After this period, the link will expire and the receipt url value will be null.

recipient_notificationobject
Details about the OutboundPayment notification settings for recipient.
- recipient_notification.settingenum
  Configuration option to enable or disable notifications to recipients. Do not send notifications when setting is NONE. Default to account setting when setting is CONFIGURED or not set.
  Possible enum values
  configured
  Default to account setting.
  none
  Do not send email.

statement_descriptorstring
The description that appears on the receiving end for an OutboundPayment (for example, bank statement for external bank transfer). It will default to STRIPE if not set on the account settings.

statusenum

Current status of the OutboundPayment: processing, failed, posted, returned, canceled. An OutboundPayment is processing if it has been created and is processing. The status changes to posted once the OutboundPayment has been “confirmed” and funds have left the account, or to failed or canceled. If an OutboundPayment fails to arrive at its payout method, its status will change to returned.

Possible enum values

canceled

A user canceled the OutboundPayment before posting. Stripe returns the funds to the user by voiding the pending Transaction.

failed

The OutboundPayment failed to confirm. Stripe returns the funds to the user by voiding the pending Transaction.

posted

The OutboundPayment posted and funds have left the account. The underlying Transaction posts.

processing

The OutboundPayment starting state. Funds are “held” by a pending Transaction (but are still part of the current balance). The OutboundPayment might be cancelable by the user, depending on the value of the cancelable field.

returned

The OutboundPayment failed to successfully arrive at the destination. Funds return to the user with a second posted Transaction attached to the same flow.

status_detailsnullable object

Status details for an OutboundPayment in a failed or returned state.

status_details.failednullable object

The failed status reason.

status_details.failed.reasonenum

The failed status reason.

Possible enum values

payout_method_declined

The outbound flow to this payout method was declined.

payout_method_does_not_exist

Payout method used for this outbound flow does not exist.

payout_method_expired

Payout method used for this outbound flow expired.

payout_method_unsupported

Payout method used for this outbound flow is unsupported.

payout_method_usage_frequency_limit_exceeded

The usage frequency limit for this payout method was exceeded.

unknown_failure

Unknown failure.

status_details.returnednullable object

The returned status reason.

status_details.returned.reasonenum

The returned status reason.

Possible enum values

payout_method_canceled_by_customer

The outbound flow to this payout method was canceled by customer.

payout_method_closed

Payout method account used for this outbound flow is closed.

payout_method_currency_unsupported

Currency is not supported by the payout method account.

payout_method_does_not_exist

Payout method account used for this outbound flow does not exist.

payout_method_holder_address_incorrect

Address on the payout method account is incorrect.

payout_method_holder_details_incorrect

The payout method account holder’s details are incorrect.

payout_method_holder_name_incorrect

Name on the payout method account is incorrect.

payout_method_invalid_account_number

The outbound flow to this payout method has an invalid account number.

payout_method_restricted

Payout method account used for this outbound flow is restricted.

recalled

The outbound flow to this payout method was recalled.

Show 1 more

status_transitionsnullable object
Hash containing timestamps of when the object transitioned to a particular status.
- status_transitions.canceled_atnullable timestamp
  Timestamp describing when an OutboundPayment changed status to canceled. Represented as a RFC 3339 date & time UTC value in millisecond precision, for example: 2022-09-18T13:22:18.123Z.
- status_transitions.failed_atnullable timestamp
  Timestamp describing when an OutboundPayment changed status to failed. Represented as a RFC 3339 date & time UTC value in millisecond precision, for example: 2022-09-18T13:22:18.123Z.
- status_transitions.posted_atnullable timestamp
  Timestamp describing when an OutboundPayment changed status to posted. Represented as a RFC 3339 date & time UTC value in millisecond precision, for example: 2022-09-18T13:22:18.123Z.
- status_transitions.returned_atnullable timestamp
  Timestamp describing when an OutboundPayment changed status to returned. Represented as a RFC 3339 date & time UTC value in millisecond precision, for example: 2022-09-18T13:22:18.123Z.

toobject
To which payout method the OutboundPayment was sent.
- to.creditedobject
  The monetary amount being credited to the destination.
  to.credited.currencystring
  A lowercase alpha3 currency code like “usd”.
  to.credited.valueinteger
  In minor units like 123 for 1.23 USD.
- to.payout_methodstring
  The payout method which the OutboundPayment uses to send payout.
- to.recipientstring
  To which account the OutboundPayment is sent.

trace_idobjectPreview feature
A unique identifier that can be used to track this OutboundPayment with recipient bank. Banks might call this a “reference number” or something similar.
- trace_id.statusenum
  Possible values are pending, supported, and unsupported. Initially set to pending, it changes to supported when the recipient bank provides a trace ID, or unsupported if the recipient bank doesn’t support it. Note that this status may not align with the OutboundPayment or OutboundTransfer status and can remain pending even after the payment or transfer is posted.
  Possible enum values
  pending
  Pending to receive TraceId information from recipient bank.
  supported
  TraceId is supported by the recipient bank.
  unsupported
  TraceId is not supported by the recipient bank.
- trace_id.valuenullable string
  The trace ID value if trace_id.status is supported, otherwise empty.

Error Codes

400outbound_payment_account_not_configured_as_recipient

Error returned when the recipient account in the OutboundPayment request is not configured as a recipient.

400outbound_payment_amount_too_large_for_payout_method

Error returned when the specified amount exceeds the payout method’s amount limits.

400outbound_payment_amount_too_large_for_selected_delivery_option

Error returned when user selected a delivery option but the specified amount exceeds the method limits.

400outbound_payment_card_payout_method_not_supported

Error returned when the provided Card payout method is not eligible for outbound payment.

400outbound_payment_cop_not_accepted

Error returned when the Confirmation of Payee is not accepted.

400outbound_payment_default_payout_method_config_not_found

Error returned when a payout method is not provided in the OutboundPayment request and the recipient account does not have a default payout method.

400outbound_payment_delivery_option_not_supported

Error returned when the selected delivery option is not supported for the payout method.

400outbound_payment_from_balance_unsupported_currency

Error returned when the balance type in the OutboundPayment request does not support the provided currency.

400outbound_payment_fx_quote_expired

Error returned when rate locking in the used OBPQ is expired.

400outbound_payment_insufficient_funds

Error returned when the balance of provided financial account and balance type in the OutboundPayment request does not have enough funds.

400outbound_payment_invalid_payout_method_country

Error returned when the payout method country does not match the recipient account country.

400outbound_payment_no_suitable_delivery_options_for_large_amount

Error returned when user does not specify the delivery option or provides automatic, and the amount exceeds all the possible delivery options for this payout method.

400outbound_payment_not_allowed

Error returned when the user is not allowed to make this OutboundPayment request.

400outbound_payment_payout_method_expired

Error returned when the provided payout method is expired.

400outbound_payment_quote_large_rate_drift

Error returned when the FX rate drift beyond threshold.

400outbound_payment_quote_mismatch

Error returned when key money movement fields on outbound payment quote creation request don’t match outbound payment creation request, including from, to, amount and delivery_options.

400outbound_payment_quote_missing

Error returned when outbound payment quote is missing for CBPs that requires fee and amount estimates prior to OBP initiation.

400outbound_payment_recipient_amount_limit_exceeded

Error returned when the recipient’s recent total amount in outbound payments has exceeded its limit.

400outbound_payment_recipient_count_limit_exceeded

Error returned when the recipient’s recent outbound payment count has exceeded its limit.

400outbound_payment_recipient_email_does_not_exist

Error returned when the user enables notifications in the OutboundPayment request, but an email is not set up on the recipient account.

400outbound_payment_recipient_feature_not_active

Error returned when recipient does not have the active features required to receive funds from this OutboundPayment request.

400outbound_payment_recipient_feature_not_active_for_suitable_delivery_option

Error returned when user does not specify the delivery option or provides automatic, and recipient feature is not active for suitable delivery option.

400outbound_payment_unsupported_currency

Error returned when the payout method does not support the request’s payout method currency.

404outbound_payment_from_balance_type_not_found

Deprecated. Error returned when balance type of provided financial account in the OutboundPayment request cannot be identified.

404outbound_payment_from_financial_account_not_found

Error returned when financial account in the OutboundPayment request cannot be identified.

404outbound_payment_invalid_payout_method

Error returned when the payout method in the OutboundPayment request cannot be identified.

404outbound_payment_to_recipient_not_found

Error returned when the recipient account in the OutboundPayment request cannot be identified.

409idempotency_conflict

An idempotent retry results in resource conflicts.

409idempotency_error

An idempotent retry occurred with different request parameters.

POST /v2/money_management/outbound_payments

curl -X POST https://api.stripe.com/v2/money_management/outbound_payments \
  -H "Authorization: Bearer sk_test_BQokikJ...2HlWgH4olfQ2sk_test_BQokikJOvBiI2HlWgH4olfQ2" \
  -H "Stripe-Version: 2025-05-28.preview" \
  --json '{
    "from": {
        "financial_account": "fa_test_65NybHaQx7KJxDc22rZ16NybHIZ4SQ3LORe4rpuNGDIXEO",
        "currency": "usd"
    },
    "to": {
        "recipient": "acct_test_61Nyc6oHjbwlpjhvd66Nyc6oZ4SQv89ZZAqvHiCECJ3g",
        "payout_method": "usba_test_61Nyd9YFBVUzLyxXZ16Nyc6oZ4SQv89ZZAqvHiCEC9VQ",
        "currency": "usd"
    },
    "amount": {
        "value": 1000,
        "currency": "usd"
    },
    "description": "Streamer earnings"
  }'

Response

{
  "id": "obp_test_65OAfT9tVl3u223h0he16NybHIZ4SQ3LORe4rpuNGDIKCO",
  "object": "v2.money_management.outbound_payment",
  "amount": {
    "value": 1000,
    "currency": "usd"
  },
  "from": {
    "debited": {
      "value": 1000,
      "currency": "usd"
    },
    "financial_account": "fa_test_65NybHaQx7KJxDc22rZ16NybHIZ4SQ3LORe4rpuNGDIXEO"
  },
  "to": {
    "credited": {
      "value": 1000,
      "currency": "usd"
    },
    "recipient": "acct_test_61Nyc6oHjbwlpjhvd66Nyc6oZ4SQv89ZZAqvHiCECJ3g",
    "payout_method": "usba_test_61Nyd9YFBVUzLyxXZ16Nyc6oZ4SQv89ZZAqvHiCEC9VQ"
  },
  "delivery_options": {
    "bank_account": "automatic"
  },
  "statement_descriptor": "Payment for streaming earnings",
  "cancelable": true,
  "description": "Streamer earnings",
  "status": "processing",
  "status_transitions": {},
  "receipt_url": "https://payments.stripe.com/transaction_receipt/CCMaIwohd2tzcF90ZXN0XzZOeWJISVo0U1EzTE9SZTRycHVOR0RJKOPfpqIGMgZn4xRNQi06oQGUu_fPQJBHgptVXysoOIKNwdFbokEtoKYNk662ox8FRx8ldoJpnlZyFXloJjMW5AQ5dqSks8HidH5PkHyYO91-dYHRZ8kj93mfh2l_efexFDN6EmiZj21RiNDALXuagy2MHFmfrkh6ZiAnjp-MOgqg8IM1RA5Ry5IDL-21Xiair1jWxuVJb3inbrbntL3nk6yjUtXcd_QLofG-Sj2Yz9-NEA",
  "created": "2023-04-26T23:12:35.952Z",
  "expected_arrival_date": "2023-04-28T00:00:00Z",
  "recipient_notification": {
    "setting": "configured"
  },
  "livemode": false
}

Need help? Contact Support.
Check out our changelog.
Questions? Contact Sales.
LLM? Read llms.txt.
Powered by Markdoc

Create an OutboundPayment object v2

Parameters

amountobjectRequired

amount.currencystringRequired

amount.valueintegerRequired

fromobjectRequired

from.currencystringRequired

from.financial_accountstringRequired

toobjectRequired

to.currencystring

to.payout_methodstring

to.recipientstringRequired

delivery_optionsobject

delivery_options.bank_accountenum

descriptionstring

metadatamap

outbound_payment_quotestringPreview feature

recipient_notificationobject

recipient_notification.settingenumRequired

Returns

Response attributes

idstring

objectstring, value is "v2.money_management.outbound_payment"

amountobject

amount.currencystring

amount.valueinteger

cancelableboolean

createdtimestamp

delivery_optionsnullable object

delivery_options.bank_accountnullable enum

descriptionnullable string

expected_arrival_datenullable timestamp

fromobject

from.debitedobject

from.debited.currencystring

from.debited.valueinteger

from.financial_accountstring

livemodeboolean

metadatanullable map

outbound_payment_quotenullable stringPreview feature

receipt_urlnullable string

recipient_notificationobject

recipient_notification.settingenum

statement_descriptorstring

statusenum

status_detailsnullable object

status_details.failednullable object

status_details.failed.reasonenum

status_details.returnednullable object

status_details.returned.reasonenum

status_transitionsnullable object

status_transitions.canceled_atnullable timestamp

status_transitions.failed_atnullable timestamp

status_transitions.posted_atnullable timestamp

status_transitions.returned_atnullable timestamp

toobject

to.creditedobject

to.credited.currencystring

to.credited.valueinteger

to.payout_methodstring

to.recipientstring

trace_idobjectPreview feature

trace_id.statusenum

trace_id.valuenullable string