Struct PaymentSession

Source

pub struct PaymentSession {Show 23 fields
    pub amount: Option<String>,
    pub asset: Option<Asset>,
    pub authorizations: Vec<Authorization>,
    pub auto_capture: bool,
    pub balances: Option<PaymentSessionBalances>,
    pub cancellation_reason: Option<String>,
    pub captures: Vec<Capture>,
    pub created_at: Option<DateTime<Utc>>,
    pub customer_display: Option<CustomerDisplay>,
    pub entity_id: Option<String>,
    pub expiries: Option<PaymentExpiries>,
    pub external_reference_id: Option<PaymentSessionExternalReferenceId>,
    pub metadata: Option<Metadata>,
    pub payment_session_id: Option<PaymentSessionId>,
    pub redirect: Option<PaymentRedirect>,
    pub refunds: Vec<Refund>,
    pub source: Option<PaymentSessionSource>,
    pub status: Option<PaymentSessionStatus>,
    pub target: Option<PaymentSessionTarget>,
    pub updated_at: Option<DateTime<Utc>>,
    pub url: Option<Url>,
    pub voids: Vec<Void>,
    pub x402_url: Option<Url>,
}

Expand description

Tracks the full lifecycle of a payment from creation through settlement. Typical flow: Create → Authorize (via payment method) → Capture. Optional: Void to release uncaptured funds, or Refund to return captured funds.

JSON schema

{
 "description": "Tracks the full lifecycle of a payment from creation through settlement. Typical flow: **Create** → **Authorize** (via payment method) → **Capture**. Optional: **Void** to release uncaptured funds, or **Refund** to return captured funds.",
 "examples": [
   {
     "amount": "1.00",
     "asset": "usdc",
     "autoCapture": false,
     "balances": {
       "capturable": "0",
       "captured": "0",
       "refundable": "0",
       "refunded": "0"
     },
     "createdAt": "2025-06-15T12:00:00.000Z",
     "customerDisplay": {
       "displayAmount": {
         "amount": "1.37",
         "currency": "cad"
       },
       "merchantName": "Acme Store"
     },
     "entityId": "entity_af2937b0-9846-4fe7-bfe9-ccc22d935114",
     "expiries": {
       "authorizationExpiresAt": "2025-12-31T23:59:59.000Z",
       "captureExpiresAt": "2026-01-15T23:59:59.000Z",
       "refundExpiresAt": "2026-02-15T23:59:59.000Z"
     },
     "externalReferenceId": "merchant-order-abc123",
     "metadata": {
       "customer_id": "cust_12345",
       "order_reference": "order-67890"
     },
     "paymentSessionId": "paymentSession_82c879c1-84e1-44ed-a8c2-1ac239cf09ad",
     "redirect": {
       "failureUrl": "https://merchant.example.com/payment/failed",
       "successUrl": "https://merchant.example.com/payment/success"
     },
     "status": "created",
     "target": {
       "address": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
       "network": "base"
     },
     "updatedAt": "2025-06-15T12:05:00.000Z",
     "url": "https://payments.coinbase.com/payment-sessions/paymentSession_82c879c1-84e1-44ed-a8c2-1ac239cf09ad",
     "x402Url": "https://api.cdp.coinbase.com/platform/v2/payment-sessions/paymentSession_82c879c1-84e1-44ed-a8c2-1ac239cf09ad/authorizations/x402"
   }
 ],
 "type": "object",
 "properties": {
   "amount": {
     "description": "A decimal representation of the payment amount, denominated in `asset`.",
     "examples": [
       "1.00"
     ],
     "type": "string"
   },
   "asset": {
     "description": "The symbol of the asset for the payment amount.",
     "examples": [
       "usdc"
     ],
     "allOf": [
       {
         "$ref": "#/components/schemas/Asset"
       }
     ]
   },
   "authorizations": {
     "description": "The authorizations for this payment session.",
     "type": "array",
     "items": {
       "$ref": "#/components/schemas/Authorization"
     }
   },
   "autoCapture": {
     "description": "When true, a capture is automatically created after a successful authorization. When false or omitted, the merchant must create captures manually via the captures endpoint.",
     "default": false,
     "examples": [
       false
     ],
     "type": "boolean"
   },
   "balances": {
     "$ref": "#/components/schemas/PaymentSessionBalances"
   },
   "cancellationReason": {
     "description": "The reason the payment session was canceled. Only present when the session has been canceled.",
     "examples": [
       "Customer requested cancellation."
     ],
     "type": "string"
   },
   "captures": {
     "description": "The captures for this payment session.",
     "type": "array",
     "items": {
       "$ref": "#/components/schemas/Capture"
     }
   },
   "createdAt": {
     "description": "The UTC ISO 8601 timestamp at which the payment session was created.",
     "examples": [
       "2025-06-15T12:00:00.000Z"
     ],
     "type": "string",
     "format": "date-time"
   },
   "customerDisplay": {
     "$ref": "#/components/schemas/CustomerDisplay"
   },
   "entityId": {
     "description": "The ID of the entity that owns the payment session.",
     "examples": [
       "entity_af2937b0-9846-4fe7-bfe9-ccc22d935114"
     ],
     "type": "string"
   },
   "expiries": {
     "$ref": "#/components/schemas/PaymentExpiries"
   },
   "externalReferenceId": {
     "description": "A merchant-provided internal identifier for this payment session, from the merchant's own system—not visible to the payer. It must not contain personally identifiable information (PII) or payment credentials.",
     "examples": [
       "merchant-order-abc123"
     ],
     "type": "string",
     "maxLength": 256
   },
   "metadata": {
     "$ref": "#/components/schemas/Metadata"
   },
   "paymentSessionId": {
     "description": "The unique identifier of the payment session.",
     "examples": [
       "paymentSession_82c879c1-84e1-44ed-a8c2-1ac239cf09ad"
     ],
     "allOf": [
       {
         "$ref": "#/components/schemas/PaymentSessionId"
       }
     ]
   },
   "redirect": {
     "$ref": "#/components/schemas/PaymentRedirect"
   },
   "refunds": {
     "description": "The refunds for this payment session.",
     "type": "array",
     "items": {
       "$ref": "#/components/schemas/Refund"
     }
   },
   "source": {
     "description": "The source of the payment session. Set after a successful authorization. Not present before authorization.",
     "examples": [
       {
         "address": "0xAbC1234567890aBcDeF1234567890AbCdEf123456",
         "asset": "usdc",
         "network": "base"
       }
     ],
     "allOf": [
       {
         "$ref": "#/components/schemas/PaymentSessionSource"
       }
     ]
   },
   "status": {
     "description": "The most recent meaningful event on the payment session.",
     "examples": [
       "created"
     ],
     "allOf": [
       {
         "$ref": "#/components/schemas/PaymentSessionStatus"
       }
     ]
   },
   "target": {
     "description": "The target of the payment session.",
     "examples": [
       {
         "address": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
         "network": "base"
       }
     ],
     "allOf": [
       {
         "$ref": "#/components/schemas/PaymentSessionTarget"
       }
     ]
   },
   "updatedAt": {
     "description": "The UTC ISO 8601 timestamp at which the payment session was last updated.",
     "examples": [
       "2025-06-15T12:05:00.000Z"
     ],
     "type": "string",
     "format": "date-time"
   },
   "url": {
     "description": "A URL to the hosted payment page where the payer can complete this payment session.",
     "readOnly": true,
     "examples": [
       "https://payments.coinbase.com/payment-sessions/paymentSession_82c879c1-84e1-44ed-a8c2-1ac239cf09ad"
     ],
     "allOf": [
       {
         "$ref": "#/components/schemas/Url"
       }
     ]
   },
   "voids": {
     "description": "The voids for this payment session.",
     "type": "array",
     "items": {
       "$ref": "#/components/schemas/Void"
     }
   },
   "x402Url": {
     "description": "URL for the hosted x402 payment flow. This endpoint expects an HTTP **POST** request (for example, submitting the x402 payment via request headers); do not treat it as a page opened with GET alone. Only present when the payment target supports a wallet source.",
     "readOnly": true,
     "examples": [
       "https://api.cdp.coinbase.com/platform/v2/payment-sessions/paymentSession_82c879c1-84e1-44ed-a8c2-1ac239cf09ad/authorizations/x402"
     ],
     "allOf": [
       {
         "$ref": "#/components/schemas/Url"
       }
     ]
   }
 }
}

Fields§

§amount: Option<String>

A decimal representation of the payment amount, denominated in asset.

§asset: Option<Asset>

The symbol of the asset for the payment amount.

§authorizations: Vec<Authorization>

The authorizations for this payment session.

§auto_capture: bool

When true, a capture is automatically created after a successful authorization. When false or omitted, the merchant must create captures manually via the captures endpoint.

§balances: Option<PaymentSessionBalances>§cancellation_reason: Option<String>

The reason the payment session was canceled. Only present when the session has been canceled.

§captures: Vec<Capture>

The captures for this payment session.

§created_at: Option<DateTime<Utc>>

The UTC ISO 8601 timestamp at which the payment session was created.

§customer_display: Option<CustomerDisplay>§entity_id: Option<String>

The ID of the entity that owns the payment session.

§expiries: Option<PaymentExpiries>§external_reference_id: Option<PaymentSessionExternalReferenceId>

A merchant-provided internal identifier for this payment session, from the merchant’s own system—not visible to the payer. It must not contain personally identifiable information (PII) or payment credentials.

§metadata: Option<Metadata>§payment_session_id: Option<PaymentSessionId>

The unique identifier of the payment session.

§redirect: Option<PaymentRedirect>§refunds: Vec<Refund>

The refunds for this payment session.

§source: Option<PaymentSessionSource>

The source of the payment session. Set after a successful authorization. Not present before authorization.

§status: Option<PaymentSessionStatus>

The most recent meaningful event on the payment session.

§target: Option<PaymentSessionTarget>

The target of the payment session.

§updated_at: Option<DateTime<Utc>>

The UTC ISO 8601 timestamp at which the payment session was last updated.

§url: Option<Url>

A URL to the hosted payment page where the payer can complete this payment session.

§voids: Vec<Void>

The voids for this payment session.

§x402_url: Option<Url>

URL for the hosted x402 payment flow. This endpoint expects an HTTP POST request (for example, submitting the x402 payment via request headers); do not treat it as a page opened with GET alone. Only present when the payment target supports a wallet source.

Struct PaymentSession Copy item path

Fields§

Implementations§

impl PaymentSession

pub fn builder() -> PaymentSession

Trait Implementations§

impl Clone for PaymentSession

fn clone(&self) -> Self

fn clone_from(&mut self, source: &Self)

impl Debug for PaymentSession

fn fmt(&self, f: &mut Formatter<'_>) -> Result

impl Default for PaymentSession

fn default() -> Self

impl<'de> Deserialize<'de> for PaymentSession

fn deserialize<__D>(__deserializer: __D) -> Result<Self, __D::Error>where __D: Deserializer<'de>,

impl From<&PaymentSession> for PaymentSession

fn from(value: &PaymentSession) -> Self

impl From<PaymentSession> for PaymentSession

fn from(value: PaymentSession) -> Self

impl Serialize for PaymentSession

fn serialize<__S>(&self, __serializer: __S) -> Result<__S::Ok, __S::Error>where __S: Serializer,

impl TryFrom<PaymentSession> for PaymentSession

type Error = ConversionError

fn try_from(value: PaymentSession) -> Result<Self, ConversionError>

Auto Trait Implementations§

impl Freeze for PaymentSession

impl RefUnwindSafe for PaymentSession

impl Send for PaymentSession

impl Sync for PaymentSession

impl Unpin for PaymentSession

impl UnsafeUnpin for PaymentSession

impl UnwindSafe for PaymentSession

Blanket Implementations§

impl<T> Any for Twhere T: 'static + ?Sized,

fn type_id(&self) -> TypeId

impl<T> Borrow<T> for Twhere T: ?Sized,

fn borrow(&self) -> &T

impl<T> BorrowMut<T> for Twhere T: ?Sized,

fn borrow_mut(&mut self) -> &mut T

impl<T> CloneToUninit for Twhere T: Clone,

unsafe fn clone_to_uninit(&self, dest: *mut u8)

impl<T> DeserializeOwned for Twhere T: for<'de> Deserialize<'de>,

impl<T> From<T> for T

fn from(t: T) -> T

impl<T> Instrument for T

fn instrument(self, span: Span) -> Instrumented<Self> ⓘ

fn in_current_span(self) -> Instrumented<Self> ⓘ

impl<T, U> Into<U> for Twhere U: From<T>,

fn into(self) -> U

impl<T> PolicyExt for Twhere T: ?Sized,

fn and<P, B, E>(self, other: P) -> And<T, P>where T: Sized + Policy<B, E>, P: Policy<B, E>,

fn or<P, B, E>(self, other: P) -> Or<T, P>where T: Sized + Policy<B, E>, P: Policy<B, E>,

impl<T> Same for T

type Output = T

impl<T> ToOwned for Twhere T: Clone,

type Owned = T

fn to_owned(&self) -> T

fn clone_into(&self, target: &mut T)

impl<T, U> TryFrom<U> for Twhere U: Into<T>,

type Error = !

fn try_from(value: U) -> Result<T, !>

impl<T, U> TryInto<U> for Twhere U: TryFrom<T>,

type Error = <U as TryFrom<T>>::Error

fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

impl<V, T> VZip<V> for Twhere V: MultiLane<T>,

fn vzip(self) -> V

impl<T> WithSubscriber for T

fn with_subscriber<S>(self, subscriber: S) -> WithDispatch<Self> ⓘwhere S: Into<Dispatch>,

fn with_current_subscriber(self) -> WithDispatch<Self> ⓘ

Struct PaymentSession

fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
where __D: Deserializer<'de>,

fn serialize<S>(&self, serializer: S) -> Result<S::Ok, S::Error>
where S: Serializer,

impl<T> Any for T
where T: 'static + ?Sized,

impl<T> Borrow<T> for T
where T: ?Sized,

impl<T> BorrowMut<T> for T
where T: ?Sized,

impl<T> CloneToUninit for T
where T: Clone,

impl<T> DeserializeOwned for T
where T: for<'de> Deserialize<'de>,

impl<T, U> Into<U> for T
where U: From<T>,

impl<T> PolicyExt for T
where T: ?Sized,

fn and<P, B, E>(self, other: P) -> And<T, P>
where T: Sized + Policy<B, E>, P: Policy<B, E>,

fn or<P, B, E>(self, other: P) -> Or<T, P>
where T: Sized + Policy<B, E>, P: Policy<B, E>,

impl<T> ToOwned for T
where T: Clone,

impl<T, U> TryFrom<U> for T
where U: Into<T>,

impl<T, U> TryInto<U> for T
where U: TryFrom<T>,

impl<V, T> VZip<V> for T
where V: MultiLane<T>,

fn with_subscriber<S>(self, subscriber: S) -> WithDispatch<Self> ⓘ
where S: Into<Dispatch>,