@coinbase/cdp-sdk/src/openapi-client/generated/payment-sessions/payment-sessions.ts

SDK for interacting with the Coinbase Developer Platform Wallet API

/**
 * Generated by orval v7.21.0 🍺
 * Do not edit manually.
 * Coinbase Developer Platform APIs
 * The Coinbase Developer Platform APIs - leading the world's transition onchain.
 * OpenAPI spec version: 2.0.0
 */
import type {
  Authorization,
  AuthorizationId,
  Balances,
  CancelPaymentSessionRequest,
  Capture,
  CaptureId,
  CoinbaseAuthorizationRequest,
  CreateCaptureRequest,
  CreatePaymentSessionRequest,
  CreateRefundRequest,
  CreateVoidRequest,
  Error,
  GetWalletAuthorizationOptionsParams,
  ListPaymentSessionAuthorizations200,
  ListPaymentSessionAuthorizationsParams,
  ListPaymentSessionCaptures200,
  ListPaymentSessionCapturesParams,
  ListPaymentSessionRefunds200,
  ListPaymentSessionRefundsParams,
  ListPaymentSessionVoids200,
  ListPaymentSessionVoidsParams,
  ListPaymentSessions200,
  ListPaymentSessionsParams,
  MandateAuthorizationRequest,
  PaymentSession,
  PaymentSessionId,
  Refund,
  RefundId,
  Void,
  VoidId,
  WalletAuthorizationOptionsResponse,
  WalletAuthorizationRequest,
} from "../coinbaseDeveloperPlatformAPIs.schemas.js";

import { cdpApiClient } from "../../cdpApiClient.js";

type SecondParameter<T extends (...args: never) => unknown> = Parameters<T>[1];

/**
 * Returns the balances held in the Coinbase account.

The `available` amount is the immediately spendable balance. The `total` amount also includes funds currently on hold. Both amounts are returned as decimal strings with 2 decimal places (e.g. `"50.00"`).

**Authentication:** Requires a Coinbase OAuth Bearer token with the `coinbase:stablecoins:balance-read` scope.

**Returned assets:** Currently always returns a single USDC entry. If the payer holds no USDC, the entry is still returned with an `available` and `total` of `"0"` so callers do not need to special-case a missing asset. Additional assets may be returned in the future without a contract change.
 * @summary List Coinbase account balances
 */
export const listCoinbaseAccountBalances = (
  options?: SecondParameter<typeof cdpApiClient<Balances>>,
) => {
  return cdpApiClient<Balances>({ url: `/v2/coinbase-accounts/balances`, method: "GET" }, options);
};
/**
 * Creates a payment session that defines what is being paid — amount, asset, and target. Optionally configure execution behavior, expiry deadlines, redirect URLs, and metadata.

If expiry deadlines are omitted, sensible defaults are applied (1 day for authorization, 7 days for capture, 30 days for refund). Expiries must be in ascending order — see the `expiries` object for details and constraints.

Returns the session in `created` status. Next step: call one of the authorization endpoints (wallet or Coinbase) to authorize the payment.
 * @summary Create a payment session
 */
export const createPaymentSession = (
  createPaymentSessionRequest: CreatePaymentSessionRequest,
  options?: SecondParameter<typeof cdpApiClient<PaymentSession>>,
) => {
  return cdpApiClient<PaymentSession>(
    {
      url: `/v2/payment-sessions`,
      method: "POST",
      headers: { "Content-Type": "application/json" },
      data: createPaymentSessionRequest,
    },
    options,
  );
};
/**
 * Returns a paginated list of payment sessions that the API key has permission to access.
 * @summary List payment sessions
 */
export const listPaymentSessions = (
  params?: ListPaymentSessionsParams,
  options?: SecondParameter<typeof cdpApiClient<ListPaymentSessions200>>,
) => {
  return cdpApiClient<ListPaymentSessions200>(
    { url: `/v2/payment-sessions`, method: "GET", params },
    options,
  );
};
/**
 * Retrieves a single payment session by its ID, including its current status, balances, and associated metadata. The API key must have permission to access the requested session.
 * @summary Get a payment session
 */
export const getPaymentSession = (
  paymentSessionId: PaymentSessionId,
  options?: SecondParameter<typeof cdpApiClient<PaymentSession>>,
) => {
  return cdpApiClient<PaymentSession>(
    { url: `/v2/payment-sessions/${paymentSessionId}`, method: "GET" },
    options,
  );
};
/**
 * Cancels a payment session before any funds have been authorized or captured. The session must be in `created` status. Cancel is blocked while any authorization action is pending.

Once canceled, no further actions can be performed on the session. This is the only way to terminate a pre-authorization session — expiry deadlines block actions but do not automatically transition the session to a terminal state.
 * @summary Cancel a payment session
 */
export const cancelPaymentSession = (
  paymentSessionId: PaymentSessionId,
  cancelPaymentSessionRequest: CancelPaymentSessionRequest,
  options?: SecondParameter<typeof cdpApiClient<PaymentSession>>,
) => {
  return cdpApiClient<PaymentSession>(
    {
      url: `/v2/payment-sessions/${paymentSessionId}/cancel`,
      method: "POST",
      headers: { "Content-Type": "application/json" },
      data: cancelPaymentSessionRequest,
    },
    options,
  );
};
/**
 * Returns the available wallet authorization options for a payment session. The session must be in `created` status.

Provide one or more payer wallet addresses as query parameters. Each option specifies the currency, amount, network, and payloads the payer must sign to authorize the payment. Present the options to the payer and let them choose one, then call **Authorize Wallet** with the selected option.

This is a stateless read operation — the session is not modified.

If a requested address has no eligible authorization options (e.g. insufficient funds), it appears in `ineligibleAddresses` with a `code` and `message` instead of being absent from `options`. When an address is ineligible because of `insufficient_funds`, its `fundsRequired` array lists, per enabled (network, asset) combination, the current balance and required balance the payer needs to become eligible.
 * @summary Get wallet authorization options
 */
export const getWalletAuthorizationOptions = (
  paymentSessionId: PaymentSessionId,
  params: GetWalletAuthorizationOptionsParams,
  options?: SecondParameter<typeof cdpApiClient<WalletAuthorizationOptionsResponse>>,
) => {
  return cdpApiClient<WalletAuthorizationOptionsResponse>(
    {
      url: `/v2/payment-sessions/${paymentSessionId}/authorizations/wallet/options`,
      method: "GET",
      params,
    },
    options,
  );
};
/**
 * **Customer-initiated.** Authorizes a payment session using the payer's wallet. The payer signs the payloads themselves, so this call is unauthenticated. The session must be in `created` status.

The `optionId` must match one of the options returned by the **Get Wallet Authorization Options** endpoint. Include the signed payloads for the selected option.

On authorization, a hold is placed on the payer's funds. The authorization is returned in `pending` status and transitions asynchronously to `succeeded` or `failed`.

If `autoCapture` is enabled on the session, a capture is automatically created after a successful authorization.
 * @summary Authorize a payment session with a wallet
 */
export const authorizeWalletPaymentSession = (
  paymentSessionId: PaymentSessionId,
  walletAuthorizationRequest: WalletAuthorizationRequest,
  options?: SecondParameter<typeof cdpApiClient<Authorization>>,
) => {
  return cdpApiClient<Authorization>(
    {
      url: `/v2/payment-sessions/${paymentSessionId}/authorizations/wallet`,
      method: "POST",
      headers: { "Content-Type": "application/json" },
      data: walletAuthorizationRequest,
    },
    options,
  );
};
/**
 * **Customer-initiated.** Authorizes a payment session using x402. The payer supplies the payment payload, so this call is unauthenticated. The session must be in `created` status.

The client sends no request body. You may supply the base64-encoded x402-compliant payment payload in the optional **`PAYMENT-SIGNATURE`** header.

On authorization, a hold is placed on the payer's funds. The authorization is returned in `pending` status and transitions asynchronously to `succeeded` or `failed`.

**402 Payment Required** may be returned when payment must be supplied before authorization can proceed. The **402** response uses the standard CDP **`Error`** JSON body and may include a **`PAYMENT-REQUIRED`** header (see the **402** response) describing accepted networks, assets, and amounts.

If `autoCapture` is enabled on the session, a capture is automatically created after a successful authorization.
 * @summary Authorize a payment session with x402
 */
export const authorizeX402PaymentSession = (
  paymentSessionId: PaymentSessionId,
  options?: SecondParameter<typeof cdpApiClient<Authorization>>,
) => {
  return cdpApiClient<Authorization>(
    { url: `/v2/payment-sessions/${paymentSessionId}/authorizations/x402`, method: "POST" },
    options,
  );
};
/**
 * **Merchant-initiated.** The merchant charges the payer's Coinbase account using an OAuth grant the payer authorized earlier, so the payer does not need to be present at payment time. The session must be in `created` status.

**Authentication:** Requires a Coinbase OAuth Bearer token with the `coinbase:stablecoins:payment-create` scope.

On authorization, a hold is placed on the payer's funds. The authorization is returned in `pending` status and transitions asynchronously to `succeeded` or `failed`.

If `autoCapture` is enabled on the session, a capture is automatically created after a successful authorization.
 * @summary Authorize a payment session with a Coinbase account
 */
export const authorizeCoinbasePaymentSession = (
  paymentSessionId: PaymentSessionId,
  coinbaseAuthorizationRequest: CoinbaseAuthorizationRequest,
  options?: SecondParameter<typeof cdpApiClient<Authorization>>,
) => {
  return cdpApiClient<Authorization>(
    {
      url: `/v2/payment-sessions/${paymentSessionId}/authorizations/coinbase`,
      method: "POST",
      headers: { "Content-Type": "application/json" },
      data: coinbaseAuthorizationRequest,
    },
    options,
  );
};
/**
 * **Merchant-initiated.** The merchant draws against a mandate in `approval_succeeded` status using the mandate's existing approval, so no fresh signature is required and the customer does not need to be present. The session must be in `created` status and the mandate must be in `approval_succeeded` status. When more than one mandate condition applies, the first match wins: an in-flight approval or revocation returns `409` (`mandate_action_pending`); `revokedAt` set returns `422` (`mandate_revoked`); `canceledAt` set returns `422` (`mandate_canceled`); a past `expiresAt` returns `400` (`mandate_expired`); any other status returns `422` (`mandate_invalid_status`).

It requires API key authentication: unlike the payer-present wallet flow there is no per-call signature to prove consent, so the merchant authenticates as the party entitled to draw against the mandate.

The charge must fall within the mandate's `policy`. Exceeding `maxPerAuthorization` or `maxPerPeriod` returns `422` (`mandate_policy_violation`).

On authorization, a hold is placed on the payer's funds. The authorization is returned in `pending` status and transitions asynchronously to `succeeded` or `failed`. If `autoCapture` is enabled on the session, a capture is automatically created after a successful authorization.
 * @summary Authorize a payment session with a mandate
 */
export const authorizeMandatePaymentSession = (
  paymentSessionId: PaymentSessionId,
  mandateAuthorizationRequest: MandateAuthorizationRequest,
  options?: SecondParameter<typeof cdpApiClient<Authorization>>,
) => {
  return cdpApiClient<Authorization>(
    {
      url: `/v2/payment-sessions/${paymentSessionId}/authorizations/mandate`,
      method: "POST",
      headers: { "Content-Type": "application/json" },
      data: mandateAuthorizationRequest,
    },
    options,
  );
};
/**
 * Returns a paginated list of authorizations for a payment session. Each authorization represents a hold on funds and includes its current status and amount.
 * @summary List payment session authorizations
 */
export const listPaymentSessionAuthorizations = (
  paymentSessionId: PaymentSessionId,
  params?: ListPaymentSessionAuthorizationsParams,
  options?: SecondParameter<typeof cdpApiClient<ListPaymentSessionAuthorizations200>>,
) => {
  return cdpApiClient<ListPaymentSessionAuthorizations200>(
    { url: `/v2/payment-sessions/${paymentSessionId}/authorizations`, method: "GET", params },
    options,
  );
};
/**
 * Retrieves a single authorization by its ID, including its current status, amount, and any associated onchain transactions.
 * @summary Get a payment session authorization
 */
export const getPaymentSessionAuthorization = (
  paymentSessionId: PaymentSessionId,
  authorizationId: AuthorizationId,
  options?: SecondParameter<typeof cdpApiClient<Authorization>>,
) => {
  return cdpApiClient<Authorization>(
    {
      url: `/v2/payment-sessions/${paymentSessionId}/authorizations/${authorizationId}`,
      method: "GET",
    },
    options,
  );
};
/**
 * Captures authorized funds. The session must have a positive `capturable` balance and the `captureExpiresAt` deadline must not have passed.

This is an asynchronous operation. The capture is returned in `pending` status and transitions to `succeeded` or `failed`.

Multiple partial captures are allowed. If `amount` is omitted, the full remaining capturable amount is captured.
 * @summary Capture a payment session
 */
export const capturePaymentSession = (
  paymentSessionId: PaymentSessionId,
  createCaptureRequest: CreateCaptureRequest,
  options?: SecondParameter<typeof cdpApiClient<Capture>>,
) => {
  return cdpApiClient<Capture>(
    {
      url: `/v2/payment-sessions/${paymentSessionId}/captures`,
      method: "POST",
      headers: { "Content-Type": "application/json" },
      data: createCaptureRequest,
    },
    options,
  );
};
/**
 * Returns a paginated list of captures for a payment session. Each capture includes its status, amount, associated onchain transactions, and timestamps. Only captures accessible by the current API key are returned.
 * @summary List payment session captures
 */
export const listPaymentSessionCaptures = (
  paymentSessionId: PaymentSessionId,
  params?: ListPaymentSessionCapturesParams,
  options?: SecondParameter<typeof cdpApiClient<ListPaymentSessionCaptures200>>,
) => {
  return cdpApiClient<ListPaymentSessionCaptures200>(
    { url: `/v2/payment-sessions/${paymentSessionId}/captures`, method: "GET", params },
    options,
  );
};
/**
 * Retrieves a single capture by its ID, including status, captured amount, associated onchain transactions, and timestamps. Only returns the capture if the API key has permission to access it.
 * @summary Get a payment session capture
 */
export const getPaymentSessionCapture = (
  paymentSessionId: PaymentSessionId,
  captureId: CaptureId,
  options?: SecondParameter<typeof cdpApiClient<Capture>>,
) => {
  return cdpApiClient<Capture>(
    { url: `/v2/payment-sessions/${paymentSessionId}/captures/${captureId}`, method: "GET" },
    options,
  );
};
/**
 * Releases all remaining capturable funds back to the payer. The session must have a positive `capturable` balance.

This is an asynchronous operation. The void is returned in `pending` status and transitions to `succeeded` or `failed`.

After voiding, no further captures can be made. Unlike **Cancel**, which works before authorization, void works after authorization.
 * @summary Void a payment session
 */
export const voidPaymentSession = (
  paymentSessionId: PaymentSessionId,
  createVoidRequest: CreateVoidRequest,
  options?: SecondParameter<typeof cdpApiClient<Void>>,
) => {
  return cdpApiClient<Void>(
    {
      url: `/v2/payment-sessions/${paymentSessionId}/voids`,
      method: "POST",
      headers: { "Content-Type": "application/json" },
      data: createVoidRequest,
    },
    options,
  );
};
/**
 * Returns a paginated list of voids for a payment session. Each void includes its status, amount, associated onchain transactions, and timestamps. Only voids accessible by the current API key are returned.
 * @summary List payment session voids
 */
export const listPaymentSessionVoids = (
  paymentSessionId: PaymentSessionId,
  params?: ListPaymentSessionVoidsParams,
  options?: SecondParameter<typeof cdpApiClient<ListPaymentSessionVoids200>>,
) => {
  return cdpApiClient<ListPaymentSessionVoids200>(
    { url: `/v2/payment-sessions/${paymentSessionId}/voids`, method: "GET", params },
    options,
  );
};
/**
 * Retrieves a single void by its ID, including status, voided amount, associated onchain transactions, and timestamps. Only returns the void if the API key has permission to access it.
 * @summary Get a payment session void
 */
export const getPaymentSessionVoid = (
  paymentSessionId: PaymentSessionId,
  voidId: VoidId,
  options?: SecondParameter<typeof cdpApiClient<Void>>,
) => {
  return cdpApiClient<Void>(
    { url: `/v2/payment-sessions/${paymentSessionId}/voids/${voidId}`, method: "GET" },
    options,
  );
};
/**
 * Returns captured funds to the payer. The session must have a positive `refundable` balance and the `refundExpiresAt` deadline must not have passed.

This is an asynchronous operation. The refund is returned in `pending` status and transitions to `succeeded` or `failed`.

If `amount` is omitted, the full remaining refundable amount is refunded. Multiple partial refunds are supported.
 * @summary Refund a payment session
 */
export const refundPaymentSession = (
  paymentSessionId: PaymentSessionId,
  createRefundRequest: CreateRefundRequest,
  options?: SecondParameter<typeof cdpApiClient<Refund>>,
) => {
  return cdpApiClient<Refund>(
    {
      url: `/v2/payment-sessions/${paymentSessionId}/refunds`,
      method: "POST",
      headers: { "Content-Type": "application/json" },
      data: createRefundRequest,
    },
    options,
  );
};
/**
 * Returns a paginated list of refunds for a payment session. Each refund includes its status, amount, reason, associated onchain transactions, and timestamps. Only refunds accessible by the current API key are returned.
 * @summary List payment session refunds
 */
export const listPaymentSessionRefunds = (
  paymentSessionId: PaymentSessionId,
  params?: ListPaymentSessionRefundsParams,
  options?: SecondParameter<typeof cdpApiClient<ListPaymentSessionRefunds200>>,
) => {
  return cdpApiClient<ListPaymentSessionRefunds200>(
    { url: `/v2/payment-sessions/${paymentSessionId}/refunds`, method: "GET", params },
    options,
  );
};
/**
 * Retrieves a single refund by its ID, including status, refunded amount, reason, associated onchain transactions, and timestamps. Only returns the refund if the API key has permission to access it.
 * @summary Get a payment session refund
 */
export const getPaymentSessionRefund = (
  paymentSessionId: PaymentSessionId,
  refundId: RefundId,
  options?: SecondParameter<typeof cdpApiClient<Refund>>,
) => {
  return cdpApiClient<Refund>(
    { url: `/v2/payment-sessions/${paymentSessionId}/refunds/${refundId}`, method: "GET" },
    options,
  );
};
export type ListCoinbaseAccountBalancesResult = NonNullable<
  Awaited<ReturnType<typeof listCoinbaseAccountBalances>>
>;
export type CreatePaymentSessionResult = NonNullable<
  Awaited<ReturnType<typeof createPaymentSession>>
>;
export type ListPaymentSessionsResult = NonNullable<
  Awaited<ReturnType<typeof listPaymentSessions>>
>;
export type GetPaymentSessionResult = NonNullable<Awaited<ReturnType<typeof getPaymentSession>>>;
export type CancelPaymentSessionResult = NonNullable<
  Awaited<ReturnType<typeof cancelPaymentSession>>
>;
export type GetWalletAuthorizationOptionsResult = NonNullable<
  Awaited<ReturnType<typeof getWalletAuthorizationOptions>>
>;
export type AuthorizeWalletPaymentSessionResult = NonNullable<
  Awaited<ReturnType<typeof authorizeWalletPaymentSession>>
>;
export type AuthorizeX402PaymentSessionResult = NonNullable<
  Awaited<ReturnType<typeof authorizeX402PaymentSession>>
>;
export type AuthorizeCoinbasePaymentSessionResult = NonNullable<
  Awaited<ReturnType<typeof authorizeCoinbasePaymentSession>>
>;
export type AuthorizeMandatePaymentSessionResult = NonNullable<
  Awaited<ReturnType<typeof authorizeMandatePaymentSession>>
>;
export type ListPaymentSessionAuthorizationsResult = NonNullable<
  Awaited<ReturnType<typeof listPaymentSessionAuthorizations>>
>;
export type GetPaymentSessionAuthorizationResult = NonNullable<
  Awaited<ReturnType<typeof getPaymentSessionAuthorization>>
>;
export type CapturePaymentSessionResult = NonNullable<
  Awaited<ReturnType<typeof capturePaymentSession>>
>;
export type ListPaymentSessionCapturesResult = NonNullable<
  Awaited<ReturnType<typeof listPaymentSessionCaptures>>
>;
export type GetPaymentSessionCaptureResult = NonNullable<
  Awaited<ReturnType<typeof getPaymentSessionCapture>>
>;
export type VoidPaymentSessionResult = NonNullable<Awaited<ReturnType<typeof voidPaymentSession>>>;
export type ListPaymentSessionVoidsResult = NonNullable<
  Awaited<ReturnType<typeof listPaymentSessionVoids>>
>;
export type GetPaymentSessionVoidResult = NonNullable<
  Awaited<ReturnType<typeof getPaymentSessionVoid>>
>;
export type RefundPaymentSessionResult = NonNullable<
  Awaited<ReturnType<typeof refundPaymentSession>>
>;
export type ListPaymentSessionRefundsResult = NonNullable<
  Awaited<ReturnType<typeof listPaymentSessionRefunds>>
>;
export type GetPaymentSessionRefundResult = NonNullable<
  Awaited<ReturnType<typeof getPaymentSessionRefund>>
>;