# Shared Payment Tokens

This section covers the Stripe API for managing Shared Payment Tokens, which facilitate secure sharing of payment method information between Stripe accounts. There are two main types of shared payment tokens:

*   **Shared Payment Issued Token**: A token created by one Stripe account (the issuer) that represents a `PaymentMethod`. This token can be shared with another Stripe account (the seller) to enable them to process payments using the issuer's `PaymentMethod`.
*   **Shared Payment Granted Token**: A view-only representation of a `SharedPaymentIssuedToken`. This token is granted to a Stripe account (the seller) and allows them to use attributes of a shared `PaymentMethod` with a `PaymentIntent` without directly accessing the original `PaymentMethod` details.

## Shared Payment Issued Token

The `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 original `PaymentMethod` to then process the payment off-Stripe.

### Endpoints

*   **Create a SharedPaymentIssuedToken**:
    *   **POST** `/v1/shared_payment/issued_tokens`
    *   This endpoint creates a new `SharedPaymentIssuedToken` object. It requires the `payment_method` to be shared and `seller_details`. Optional parameters include `usage_limits` and `shared_metadata`.

*   **Retrieve a SharedPaymentIssuedToken**:
    *   **GET** `/v1/shared_payment/issued_tokens/:id`
    *   Retrieves an existing `SharedPaymentIssuedToken` object by its ID.

*   **Revoke a SharedPaymentIssuedToken**:
    *   **POST** `/v1/shared_payment/issued_tokens/:id/revoke`
    *   This endpoint revokes a `SharedPaymentIssuedToken`, making it unusable.

### The Shared Payment Issued Token Object

The `SharedPaymentIssuedToken` object contains the following attributes:

*   `id` (string): Unique identifier for the object.
*   `object` (string): String representing the object’s type.
*   `created` (timestamp): Time at which the object was created.
*   `deactivated_at` (timestamp, nullable): Time at which this `SharedPaymentIssuedToken` was deactivated.
*   `deactivated_reason` (enum, nullable): The reason why the `SharedPaymentIssuedToken` has been deactivated (e.g., `consumed`, `expired`, `resolved`, `revoked`).
*   `livemode` (boolean): Indicates if the object exists in live mode.
*   `next_action` (object, nullable): If present, describes the action required to make this `SharedPaymentIssuedToken` usable for payments.
*   `payment_method` (string): ID of an existing `PaymentMethod`.
*   `risk_details` (object, nullable): Risk details of the `SharedPaymentIssuedToken`.
*   `seller_details` (object, nullable): Seller details of the `SharedPaymentIssuedToken`, including `network_id` and `external_id`.
*   `setup_future_usage` (enum, nullable): Indicates if the `PaymentMethod` should be saved for future use.
*   `shared_metadata` (object, nullable): Metadata about the `SharedPaymentIssuedToken`.
*   `status` (string): The current status of the token (e.g., `active`, `revoked`).
*   `usage_details` (object, nullable): Details about how the `SharedPaymentIssuedToken` has been used.
*   `usage_limits` (object, nullable): Limits on how this `SharedPaymentToken` can be used.

## Shared Payment Granted Token

The `SharedPaymentGrantedToken` is the view-only resource of a `SharedPaymentIssuedToken`. When another Stripe merchant shares a `SharedPaymentIssuedToken` with you, you can view attributes of the shared token using the `SharedPaymentGrantedToken` API, and use it with a `PaymentIntent`.

### Endpoints

*   **Retrieve a SharedPaymentGrantedToken**:
    *   **GET** `/v1/shared_payment/granted_tokens/:id`
    *   Retrieves an existing `SharedPaymentGrantedToken` object by its ID.

*   **Create a test SharedPaymentGrantedToken**:
    *   **POST** `/v1/test_helpers/shared_payment/granted_tokens`
    *   This endpoint creates a new test `SharedPaymentGrantedToken` object. It requires the `payment_method` and `usage_limits`.

*   **Revoke a test SharedPaymentGrantedToken**:
    *   **POST** `/v1/test_helpers/shared_payment/granted_tokens/:id/revoke`
    *   This endpoint revokes a test `SharedPaymentGrantedToken` object.

### The Shared Payment Granted Token Object

The `SharedPaymentGrantedToken` object contains the following attributes:

*   `id` (string): Unique identifier for the object.
*   `object` (string): String representing the object’s type.
*   `agent_details` (object, nullable): Details about the agent that issued this `SharedPaymentGrantedToken`.
*   `created` (timestamp): Time at which the object was created.
*   `deactivated_at` (timestamp, nullable): Time at which this `SharedPaymentGrantedToken` expires and can no longer be used.
*   `deactivated_reason` (enum, nullable): The reason why the `SharedPaymentGrantedToken` has been deactivated (e.g., `consumed`, `expired`, `resolved`, `revoked`).
*   `livemode` (boolean): Indicates if the object exists in live mode.
*   `payment_method_details` (object, nullable): Details of the `PaymentMethod` that was shared via this token.
*   `risk_details` (object, nullable): Risk details of the `SharedPaymentGrantedToken`.
*   `shared_metadata` (object, nullable): Metadata about the `SharedPaymentGrantedToken`.
*   `usage_details` (object, nullable): Details about how the `SharedPaymentGrantedToken` has been used.
*   `usage_limits` (object, nullable): Limits on how this `SharedPaymentGrantedToken` can be used.