Core Resources
Payment Methods
Products
Product Catalog
Commerce
Agentic Commerce
Checkout
Payment Links
Billing
Capital
Connect
Reserves
Fraud
Issuing
Terminal
Treasury for Platforms
Payment Records
Account Evaluation
Entitlements
Sigma
Reporting
Financial Connections
Tax
Identity
Crypto
Climate
Forwarding
Privacy
Webhooks

Shared Payment Issued Tokens v1

A SharedPaymentIssuedToken is a limited-use reference to a PaymentMethod that can be created with a secret key. When shared with another Stripe account (Seller), it enables that account to either process a payment on Stripe against a PaymentMethod that your Stripe account owns, or to forward a usable credential created against the originalPaymentMethod to then process the payment off-Stripe.

Was this section helpful?YesNo
Create a SharedPaymentIssuedToken
POST/v1/shared_payment/issued_tokens
Retrieve a SharedPaymentIssuedToken
GET/v1/shared_payment/issued_tokens/:id
Revoke a SharedPaymentIssuedToken
POST/v1/shared_payment/issued_tokens/:id/revoke

The Shared Payment Issued Token object v1

Attributes

  • idstring

    Unique identifier for the object.

  • objectstring, value is "shared_payment.issued_token"

    String representing the object’s type. Objects of the same type share the same value.

  • createdtimestamp

    Time at which the object was created. Measured in seconds since the Unix epoch.

  • deactivated_atnullable timestamp

    Time at which this SharedPaymentIssuedToken was deactivated.

  • deactivated_reasonnullable enum

    The reason why the SharedPaymentIssuedToken has been deactivated.

    Possible enum values
    consumed

    consumed indicates that this token has been consumed due to hitting the allowed amount limit.

    expired

    expired indicates that this token has expired.

    resolved

    resolved indicates that this token has been resolved by a seller.

    revoked

    revoked indicates that this token has been revoked by the issuer.

  • livemodeboolean

    If the object exists in live mode, the value is true. If the object exists in test mode, the value is false.

  • next_actionnullable object

    If present, describes the action required to make this SharedPaymentIssuedToken usable for payments. Present when the token is in requires_action state.

  • payment_methodstring

    ID of an existing PaymentMethod.

  • risk_detailsnullable object

    Risk details of the SharedPaymentIssuedToken.

  • seller_detailsnullable object

    Seller details of the SharedPaymentIssuedToken, including network_id and external_id.

  • setup_future_usagenullable enum

    Indicates that you intend to save the PaymentMethod of this SharedPaymentToken to a customer later.

    Possible enum values
    on_session

    Use on_session to reuse the payment method when your customer is present in the checkout flow.

  • shared_metadatanullable map

    Metadata about the SharedPaymentIssuedToken.

  • statusnullable enum

    Status of this SharedPaymentIssuedToken, one of active, requires_action, or deactivated.

    Possible enum values
    active

    active indicates that this SharedPaymentIssuedToken is currently active and usable.

    deactivated

    deactivated indicates that this SharedPaymentIssuedToken has been deactivated.

    requires_action

    requires_action indicates that this SharedPaymentIssuedToken requires additional action from the customer before it can be used.

  • usage_detailsnullable object

    Usage details of the SharedPaymentIssuedToken

  • usage_limitsnullable object

    Usage limits of the SharedPaymentIssuedToken.

  • use_stripe_sdknullable boolean

    Set to true when using Stripe.js, iOS, or Android client-side SDKs to handle next actions.

The Shared Payment Issued Token object
{
  "id": "spt_1RgaZcFPC5QUO6ZCDVZuVA8q",
  "object": "shared_payment.issued_token",
  "livemode": false,
  "created": 1751500820,
  "deactivated_at": null,
  "deactivated_reason": null,
  "payment_method": "",
  "seller_details": {
    "external_id": null,
    "network_business_profile": "profile_test_61TU90nIeGjU7NNVXA6TU90m7ISQWsBxpcx9lASWWXTk"
  },
  "setup_future_usage": null,
  "shared_metadata": {},
  "status": "active",
  "usage_details": {
    "amount_captured": {
      "value": 0,
      "currency": "usd"
    }
  },
  "usage_limits": {
    "currency": "usd",
    "expires_at": 1751587220,
    "max_amount": 1000
  }
}

Create a SharedPaymentIssuedToken v1

POST /v1/shared_payment/issued_tokens

Creates a new SharedPaymentIssuedToken object

Parameters

  • payment_methodstringRequired

    The PaymentMethod that is going to be shared by the SharedPaymentIssuedToken.

  • seller_detailsobjectRequired

    Seller details of the SharedPaymentIssuedToken, including network_id and external_id.

  • usage_limitsobjectRequired

    Limits on how this SharedPaymentToken can be used.

  • setup_future_usageenum

    Indicates that you intend to save the PaymentMethod of this SharedPaymentToken to a customer later.

    Possible enum values
    on_session

    Use on_session to reuse the payment method when your customer is present in the checkout flow.

  • shared_metadatamap

    Set of key-value pairs that you can attach to the SharedPaymentIssuedToken. The values here are visible by default with the party that you share this SharedPaymentIssuedToken with.

Returns

Returns the newly created SharedPaymentIssuedToken

curl https://api.stripe.com/v1/shared_payment/issued_tokens \
  -u "sk_test_BQokikJOvBiI2HlWgH4olfQ2sk_test_BQokikJOvBiI2HlWgH4olfQ2:" \
  -d payment_method= \
  -d "seller_details[network_business_profile]=profile_test_61TU90nIeGjU7NNVXA6TU90m7ISQWsBxpcx9lASWWXTk" \
  -d "usage_limits[currency]=usd" \
  -d "usage_limits[expires_at]=1751587220" \
  -d "usage_limits[max_amount]=1000"
Response
{
  "id": "spt_1RgaZcFPC5QUO6ZCDVZuVA8q",
  "object": "shared_payment.issued_token",
  "livemode": false,
  "created": 1751500820,
  "deactivated_at": null,
  "deactivated_reason": null,
  "payment_method": "",
  "seller_details": {
    "external_id": null,
    "network_business_profile": "profile_test_61TU90nIeGjU7NNVXA6TU90m7ISQWsBxpcx9lASWWXTk"
  },
  "setup_future_usage": null,
  "shared_metadata": {},
  "status": "active",
  "usage_details": {
    "amount_captured": {
      "value": 0,
      "currency": "usd"
    }
  },
  "usage_limits": {
    "currency": "usd",
    "expires_at": 1751587220,
    "max_amount": 1000
  }
}