Outbound Setup Intents v2

Use the OutboundSetupIntent API to create and setup usable payout methods.

Learn more about calling API v2 endpoints.

Endpoints

POST/v2/money_management/outbound_setup_intents

POST/v2/money_management/outbound_setup_intents/:id

GET/v2/money_management/outbound_setup_intents/:id

GET/v2/money_management/outbound_setup_intents

POST/v2/money_management/outbound_setup_intents/:id/cancel

The OutboundSetupIntent object

Attributes

idstring
ID of the outbound setup intent.

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

createdtimestamp
Created timestamp.

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

next_actionnullable object
Specifies which actions needs to be taken next to continue setup of the credential.

payout_methodobject
Information about the payout method that’s created and linked to this outbound setup intent.

statusenum

Status of the outbound setup intent.

Possible enum values

canceled

The user may cancel the outbound setup intent at any time prior to reaching the succeeded status. The outbound setup intent will no longer be usable. This is a terminal status.

requires_action

Some additional setup steps need to be done to fully set up the credential for the specified usage intent. Additional steps are specified in next_action.

requires_payout_method

When the outbound setup intent is created, it begins in this status if no payout_method_data is provided. The outbound setup intent will also transition back to this status if a setup failure occurs. The user will then need to provide new payout_method_data to continue.

succeeded

If no additional setup actions need to be done i.e. credential is fully set up for the specified usage intent. This is a terminal status.

usage_intentenum
The intended money movement flow this payout method should be set up for, specified in params.
Possible enum values
payment
Setup for outbound payments.
transfer
Setup for outbound transfers.

The OutboundSetupIntent object

{
  "id": "osi_test_61SITWK7KhLsQIGAK16QsOpAPpE97EJALhqt1U5mC4kq",
  "object": "v2.money_management.outbound_setup_intent",
  "created": "2025-04-01T14:13:12.000Z",
  "next_action": {
    "confirmation_of_payee": {
      "object": "core.vault.gb_bank_account",
      "status": "uninitiated"
    },
    "type": "confirmation_of_payee"
  },
  "payout_method": {
    "id": "gbba_test_61SITWKOFwHCpdRSV16QsOpAPpE97EJALhqt1U5mCDyS",
    "object": "v2.money_management.payout_method",
    "available_payout_speeds": [
      "standard"
    ],
    "bank_account": {
      "archived": false,
      "bank_name": "Test Bank",
      "country": "GB",
      "enabled_delivery_options": [
        "local"
      ],
      "last4": "2345",
      "routing_number": "108800",
      "supported_currencies": [
        "gbp"
      ]
    },
    "created": "2025-04-01T14:13:12.295Z",
    "latest_outbound_setup_intent": "osi_test_61SITWK7KhLsQIGAK16QsOpAPpE97EJALhqt1U5mC4kq",
    "type": "bank_account",
    "usage_status": {
      "payments": "requires_action",
      "transfers": "eligible"
    }
  },
  "status": "requires_action",
  "usage_intent": "payment"
}

Create an OutboundSetupIntent object v2

Create an OutboundSetupIntent object.

Learn more about calling API v2 endpoints.

Parameters

payout_methodstring
If provided, the existing payout method resource to link to this setup intent. Any payout_method_data provided is used to update information on this linked payout method resource.

payout_method_dataobject
If no payout_method provided, used to create the underlying credential that is set up for outbound money movement. If a payout_method provided, used to update data on the credential linked to this setup intent.

usage_intentenum
Specify which type of outbound money movement this credential should be set up for (payment | transfer). If not provided, defaults to payment.
Possible enum values
payment
Setup for outbound payments.
transfer
Setup for outbound transfers.

Returns

Response attributes

idstring
ID of the outbound setup intent.

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

createdtimestamp
Created timestamp.

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

next_actionnullable object
Specifies which actions needs to be taken next to continue setup of the credential.

payout_methodobject
Information about the payout method that’s created and linked to this outbound setup intent.

statusenum

Status of the outbound setup intent.

Possible enum values

canceled

The user may cancel the outbound setup intent at any time prior to reaching the succeeded status. The outbound setup intent will no longer be usable. This is a terminal status.

requires_action

Some additional setup steps need to be done to fully set up the credential for the specified usage intent. Additional steps are specified in next_action.

requires_payout_method

succeeded

If no additional setup actions need to be done i.e. credential is fully set up for the specified usage intent. This is a terminal status.

usage_intentenum
The intended money movement flow this payout method should be set up for, specified in params.
Possible enum values
payment
Setup for outbound payments.
transfer
Setup for outbound transfers.

Error Codes

400active_outbound_setup_intent_exists_for_payout_method

Returned when the outbound setup intent cannot be created for a given payout method because the payout method already has another active outbound setup intent.

400blocked_payout_method_bank_account

Returned when the bank account cannot be added due to previous suspicious activity.

400blocked_payout_method_card

Returned in cases where the card cannot be used due to suspicious activity.

400invalid_payout_method

Returned in cases where the ID provided doesn’t correspond to a valid payout method.

400invalid_payout_method_bank_account

Returned in cases where the PayoutMethodBankAccount object provided is not valid (wrong format of credentials that does not correspond to a banking institution).

400invalid_payout_method_card

Returned in cases where the PayoutMethodCard object is not valid.

400invalid_payout_method_update

Returned when attempting to update non-updatable credential data.

400invalid_status_payout_method

Returned when the credential ID provided corresponds to a resource that does not allow usage as a payout method.

400limit_payout_method_bank_account

Returned when the number of country bank accounts has exceeded the limit in a given workspace. PayoutMethodBankAccount objects may be archived with the /archive API, at which point they will not count against the limit. If you are not passing a V2 Account ID in the Stripe-Context header you may receive this error since you are creating all your bank account objects in your own workspace.

400limit_payout_method_card

Returned when the number of cards has exceeded the limit in a given workspace. PayoutMethodCard objects may be archived with the /archive API, at which point they will not count against the limit. If you are not passing a V2 Account ID in the Stripe-Context header you may receive this error since you are creating all your bank account objects in your own workspace.

400unsupported_payout_method_bank_account

Returned in cases where Stripe is unable to support this bank at this time.

409idempotency_error

An idempotent retry occurred with different request parameters.

POST /v2/money_management/outbound_setup_intents

curl -X POST https://api.stripe.com/v2/money_management/outbound_setup_intents \
  -H "Authorization: Bearer sk_test_BQokikJ...2HlWgH4olfQ2sk_test_BQokikJOvBiI2HlWgH4olfQ2" \
  -H "Stripe-Version: 2025-06-30.preview" \
  --json '{
    "payout_method_data": {
        "type": "bank_account",
        "bank_account": {
            "country": "GB",
            "account_number": "00012345",
            "routing_number": "108800"
        }
    }
  }'

Response

{
  "id": "osi_test_61SITWK7KhLsQIGAK16QsOpAPpE97EJALhqt1U5mC4kq",
  "object": "v2.money_management.outbound_setup_intent",
  "created": "2025-04-01T14:13:12.000Z",
  "next_action": {
    "confirmation_of_payee": {
      "object": "core.vault.gb_bank_account",
      "status": "uninitiated"
    },
    "type": "confirmation_of_payee"
  },
  "payout_method": {
    "id": "gbba_test_61SITWKOFwHCpdRSV16QsOpAPpE97EJALhqt1U5mCDyS",
    "object": "v2.money_management.payout_method",
    "available_payout_speeds": [
      "standard"
    ],
    "bank_account": {
      "archived": false,
      "bank_name": "Test Bank",
      "country": "GB",
      "enabled_delivery_options": [
        "local"
      ],
      "last4": "2345",
      "routing_number": "108800",
      "supported_currencies": [
        "gbp"
      ]
    },
    "created": "2025-04-01T14:13:12.295Z",
    "latest_outbound_setup_intent": "osi_test_61SITWK7KhLsQIGAK16QsOpAPpE97EJALhqt1U5mC4kq",
    "type": "bank_account",
    "usage_status": {
      "payments": "requires_action",
      "transfers": "eligible"
    },
    "livemode": false
  },
  "status": "requires_action",
  "usage_intent": "payment",
  "livemode": false
}

Update an OutboundSetupIntent object v2

Update an OutboundSetupIntent object.

Learn more about calling API v2 endpoints.

Parameters

idstringRequired
ID of the OutboundSetupIntent object.

payout_methodstring
If provided, the existing payout method resource to link to this outbound setup intent.

payout_method_dataobject
If no payout_method provided, used to create the underlying credential that is set up for outbound money movement. If a payout_method provided, used to update data on the credential linked to this setup intent.

Returns

Response attributes

idstring
ID of the outbound setup intent.

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

createdtimestamp
Created timestamp.

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

next_actionnullable object
Specifies which actions needs to be taken next to continue setup of the credential.

payout_methodobject
Information about the payout method that’s created and linked to this outbound setup intent.

statusenum

Status of the outbound setup intent.

Possible enum values

canceled

The user may cancel the outbound setup intent at any time prior to reaching the succeeded status. The outbound setup intent will no longer be usable. This is a terminal status.

requires_action

Some additional setup steps need to be done to fully set up the credential for the specified usage intent. Additional steps are specified in next_action.

requires_payout_method

succeeded

If no additional setup actions need to be done i.e. credential is fully set up for the specified usage intent. This is a terminal status.

usage_intentenum
The intended money movement flow this payout method should be set up for, specified in params.
Possible enum values
payment
Setup for outbound payments.
transfer
Setup for outbound transfers.

Error Codes

400archived_payout_method_card

Returned when attempting to update an archived card.

400blocked_payout_method_card

Returned in cases where the card cannot be used due to suspicious activity.

400cannot_update_terminal_outbound_setup_intent

Returned when attempting to update an outbound setup intent in a terminal state (canceled or succeeded).

400invalid_payout_method_card

Returned in cases where the PayoutMethodCard object is not valid.

404not_found

The resource wasn’t found.

POST /v2/money_management/outbound_setup_intents/:id

curl -X POST https://api.stripe.com/v2/money_management/outbound_setup_intents/osi_test_61SITa5aMrGNcpWTI16QsOpAPpE97EJALhqt1U5mC85I \
  -H "Authorization: Bearer sk_test_BQokikJ...2HlWgH4olfQ2sk_test_BQokikJOvBiI2HlWgH4olfQ2" \
  -H "Stripe-Version: 2025-06-30.preview" \
  --json {"payout_method_data":{"type":"card"}}

Response

{
  "id": "osi_test_61SITa5aMrGNcpWTI16QsOpAPpE97EJALhqt1U5mC85I",
  "object": "v2.money_management.outbound_setup_intent",
  "created": "2025-04-01T14:17:05.000Z",
  "next_action": null,
  "payout_method": {
    "id": "card_test_61SITa59fSaPfOGuU16QsOpAPpE97EJALhqt1U5mC1lg",
    "object": "v2.money_management.payout_method",
    "available_payout_speeds": [
      "standard",
      "instant"
    ],
    "card": {
      "archived": false,
      "exp_month": "12",
      "exp_year": "2030",
      "last4": "5556"
    },
    "created": "2025-04-01T14:17:05.425Z",
    "latest_outbound_setup_intent": "osi_test_61SITa5aMrGNcpWTI16QsOpAPpE97EJALhqt1U5mC85I",
    "type": "card",
    "usage_status": {
      "payments": "eligible",
      "transfers": "eligible"
    },
    "livemode": false
  },
  "status": "succeeded",
  "usage_intent": "payment",
  "livemode": false
}

Retrieve an OutboundSetupIntent object v2

Retrieve an OutboundSetupIntent object.

Learn more about calling API v2 endpoints.

Parameters

idstringRequired
ID of the OutboundSetupIntent object.

Returns

Response attributes

idstring
ID of the outbound setup intent.

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

createdtimestamp
Created timestamp.

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

next_actionnullable object
Specifies which actions needs to be taken next to continue setup of the credential.

payout_methodobject
Information about the payout method that’s created and linked to this outbound setup intent.

statusenum

Status of the outbound setup intent.

Possible enum values

canceled

The user may cancel the outbound setup intent at any time prior to reaching the succeeded status. The outbound setup intent will no longer be usable. This is a terminal status.

requires_action

Some additional setup steps need to be done to fully set up the credential for the specified usage intent. Additional steps are specified in next_action.

requires_payout_method

succeeded

If no additional setup actions need to be done i.e. credential is fully set up for the specified usage intent. This is a terminal status.

usage_intentenum
The intended money movement flow this payout method should be set up for, specified in params.
Possible enum values
payment
Setup for outbound payments.
transfer
Setup for outbound transfers.

Error Codes

404not_found

The resource wasn’t found.

GET /v2/money_management/outbound_setup_intents/:id

curl https://api.stripe.com/v2/money_management/outbound_setup_intents/osi_test_61SITWK7KhLsQIGAK16QsOpAPpE97EJALhqt1U5mC4kq \
  -H "Authorization: Bearer sk_test_BQokikJ...2HlWgH4olfQ2sk_test_BQokikJOvBiI2HlWgH4olfQ2" \
  -H "Stripe-Version: 2025-06-30.preview"

Response

{
  "id": "osi_test_61SITWK7KhLsQIGAK16QsOpAPpE97EJALhqt1U5mC4kq",
  "object": "v2.money_management.outbound_setup_intent",
  "created": "2025-04-01T14:13:12.000Z",
  "next_action": {
    "confirmation_of_payee": {
      "object": "core.vault.gb_bank_account",
      "status": "uninitiated"
    },
    "type": "confirmation_of_payee"
  },
  "payout_method": {
    "id": "gbba_test_61SITWKOFwHCpdRSV16QsOpAPpE97EJALhqt1U5mCDyS",
    "object": "v2.money_management.payout_method",
    "available_payout_speeds": [
      "standard"
    ],
    "bank_account": {
      "archived": false,
      "bank_name": "Test Bank",
      "country": "GB",
      "enabled_delivery_options": [
        "local"
      ],
      "last4": "2345",
      "routing_number": "108800",
      "supported_currencies": [
        "gbp"
      ]
    },
    "created": "2025-04-01T14:13:12.295Z",
    "latest_outbound_setup_intent": "osi_test_61SITWK7KhLsQIGAK16QsOpAPpE97EJALhqt1U5mC4kq",
    "type": "bank_account",
    "usage_status": {
      "payments": "requires_action",
      "transfers": "eligible"
    },
    "livemode": false
  },
  "status": "requires_action",
  "usage_intent": "payment",
  "livemode": false
}

Outbound Setup Intents v2

The OutboundSetupIntent object

Attributes

idstring

objectstring, value is "v2.money_management.outbound_setup_intent"

createdtimestamp

livemodeboolean

next_actionnullable object

payout_methodobject

statusenum

usage_intentenum

Create an OutboundSetupIntent object v2

Parameters

payout_methodstring

payout_method_dataobject

usage_intentenum

Returns

Response attributes

idstring

objectstring, value is "v2.money_management.outbound_setup_intent"

createdtimestamp

livemodeboolean

next_actionnullable object

payout_methodobject

statusenum

usage_intentenum

Update an OutboundSetupIntent object v2

Parameters

idstringRequired

payout_methodstring

payout_method_dataobject

Returns

Response attributes

idstring

objectstring, value is "v2.money_management.outbound_setup_intent"

createdtimestamp

livemodeboolean

next_actionnullable object

payout_methodobject

statusenum

usage_intentenum

Retrieve an OutboundSetupIntent object v2

Parameters

idstringRequired

Returns

Response attributes

idstring

objectstring, value is "v2.money_management.outbound_setup_intent"

createdtimestamp

livemodeboolean

next_actionnullable object

payout_methodobject

statusenum

usage_intentenum