@coinbase/cdp-sdk
Version:
SDK for interacting with the Coinbase Developer Platform Wallet API
276 lines (248 loc) • 17.8 kB
JavaScript
;
Object.defineProperty(exports, "__esModule", { value: true });
exports.getPaymentSessionRefund = exports.listPaymentSessionRefunds = exports.refundPaymentSession = exports.getPaymentSessionVoid = exports.listPaymentSessionVoids = exports.voidPaymentSession = exports.getPaymentSessionCapture = exports.listPaymentSessionCaptures = exports.capturePaymentSession = exports.getPaymentSessionAuthorization = exports.listPaymentSessionAuthorizations = exports.authorizeMandatePaymentSession = exports.authorizeCoinbasePaymentSession = exports.authorizeX402PaymentSession = exports.authorizeWalletPaymentSession = exports.getWalletAuthorizationOptions = exports.cancelPaymentSession = exports.getPaymentSession = exports.listPaymentSessions = exports.createPaymentSession = exports.listCoinbaseAccountBalances = void 0;
const cdpApiClient_js_1 = require("../../cdpApiClient.js");
/**
* 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
*/
const listCoinbaseAccountBalances = (options) => {
return (0, cdpApiClient_js_1.cdpApiClient)({ url: `/v2/coinbase-accounts/balances`, method: "GET" }, options);
};
exports.listCoinbaseAccountBalances = listCoinbaseAccountBalances;
/**
* 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
*/
const createPaymentSession = (createPaymentSessionRequest, options) => {
return (0, cdpApiClient_js_1.cdpApiClient)({
url: `/v2/payment-sessions`,
method: "POST",
headers: { "Content-Type": "application/json" },
data: createPaymentSessionRequest,
}, options);
};
exports.createPaymentSession = createPaymentSession;
/**
* Returns a paginated list of payment sessions that the API key has permission to access.
* @summary List payment sessions
*/
const listPaymentSessions = (params, options) => {
return (0, cdpApiClient_js_1.cdpApiClient)({ url: `/v2/payment-sessions`, method: "GET", params }, options);
};
exports.listPaymentSessions = listPaymentSessions;
/**
* 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
*/
const getPaymentSession = (paymentSessionId, options) => {
return (0, cdpApiClient_js_1.cdpApiClient)({ url: `/v2/payment-sessions/${paymentSessionId}`, method: "GET" }, options);
};
exports.getPaymentSession = getPaymentSession;
/**
* 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
*/
const cancelPaymentSession = (paymentSessionId, cancelPaymentSessionRequest, options) => {
return (0, cdpApiClient_js_1.cdpApiClient)({
url: `/v2/payment-sessions/${paymentSessionId}/cancel`,
method: "POST",
headers: { "Content-Type": "application/json" },
data: cancelPaymentSessionRequest,
}, options);
};
exports.cancelPaymentSession = cancelPaymentSession;
/**
* 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
*/
const getWalletAuthorizationOptions = (paymentSessionId, params, options) => {
return (0, cdpApiClient_js_1.cdpApiClient)({
url: `/v2/payment-sessions/${paymentSessionId}/authorizations/wallet/options`,
method: "GET",
params,
}, options);
};
exports.getWalletAuthorizationOptions = getWalletAuthorizationOptions;
/**
* **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
*/
const authorizeWalletPaymentSession = (paymentSessionId, walletAuthorizationRequest, options) => {
return (0, cdpApiClient_js_1.cdpApiClient)({
url: `/v2/payment-sessions/${paymentSessionId}/authorizations/wallet`,
method: "POST",
headers: { "Content-Type": "application/json" },
data: walletAuthorizationRequest,
}, options);
};
exports.authorizeWalletPaymentSession = authorizeWalletPaymentSession;
/**
* **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
*/
const authorizeX402PaymentSession = (paymentSessionId, options) => {
return (0, cdpApiClient_js_1.cdpApiClient)({ url: `/v2/payment-sessions/${paymentSessionId}/authorizations/x402`, method: "POST" }, options);
};
exports.authorizeX402PaymentSession = authorizeX402PaymentSession;
/**
* **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
*/
const authorizeCoinbasePaymentSession = (paymentSessionId, coinbaseAuthorizationRequest, options) => {
return (0, cdpApiClient_js_1.cdpApiClient)({
url: `/v2/payment-sessions/${paymentSessionId}/authorizations/coinbase`,
method: "POST",
headers: { "Content-Type": "application/json" },
data: coinbaseAuthorizationRequest,
}, options);
};
exports.authorizeCoinbasePaymentSession = authorizeCoinbasePaymentSession;
/**
* **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
*/
const authorizeMandatePaymentSession = (paymentSessionId, mandateAuthorizationRequest, options) => {
return (0, cdpApiClient_js_1.cdpApiClient)({
url: `/v2/payment-sessions/${paymentSessionId}/authorizations/mandate`,
method: "POST",
headers: { "Content-Type": "application/json" },
data: mandateAuthorizationRequest,
}, options);
};
exports.authorizeMandatePaymentSession = authorizeMandatePaymentSession;
/**
* 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
*/
const listPaymentSessionAuthorizations = (paymentSessionId, params, options) => {
return (0, cdpApiClient_js_1.cdpApiClient)({ url: `/v2/payment-sessions/${paymentSessionId}/authorizations`, method: "GET", params }, options);
};
exports.listPaymentSessionAuthorizations = listPaymentSessionAuthorizations;
/**
* Retrieves a single authorization by its ID, including its current status, amount, and any associated onchain transactions.
* @summary Get a payment session authorization
*/
const getPaymentSessionAuthorization = (paymentSessionId, authorizationId, options) => {
return (0, cdpApiClient_js_1.cdpApiClient)({
url: `/v2/payment-sessions/${paymentSessionId}/authorizations/${authorizationId}`,
method: "GET",
}, options);
};
exports.getPaymentSessionAuthorization = getPaymentSessionAuthorization;
/**
* 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
*/
const capturePaymentSession = (paymentSessionId, createCaptureRequest, options) => {
return (0, cdpApiClient_js_1.cdpApiClient)({
url: `/v2/payment-sessions/${paymentSessionId}/captures`,
method: "POST",
headers: { "Content-Type": "application/json" },
data: createCaptureRequest,
}, options);
};
exports.capturePaymentSession = capturePaymentSession;
/**
* 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
*/
const listPaymentSessionCaptures = (paymentSessionId, params, options) => {
return (0, cdpApiClient_js_1.cdpApiClient)({ url: `/v2/payment-sessions/${paymentSessionId}/captures`, method: "GET", params }, options);
};
exports.listPaymentSessionCaptures = listPaymentSessionCaptures;
/**
* 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
*/
const getPaymentSessionCapture = (paymentSessionId, captureId, options) => {
return (0, cdpApiClient_js_1.cdpApiClient)({ url: `/v2/payment-sessions/${paymentSessionId}/captures/${captureId}`, method: "GET" }, options);
};
exports.getPaymentSessionCapture = getPaymentSessionCapture;
/**
* 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
*/
const voidPaymentSession = (paymentSessionId, createVoidRequest, options) => {
return (0, cdpApiClient_js_1.cdpApiClient)({
url: `/v2/payment-sessions/${paymentSessionId}/voids`,
method: "POST",
headers: { "Content-Type": "application/json" },
data: createVoidRequest,
}, options);
};
exports.voidPaymentSession = voidPaymentSession;
/**
* 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
*/
const listPaymentSessionVoids = (paymentSessionId, params, options) => {
return (0, cdpApiClient_js_1.cdpApiClient)({ url: `/v2/payment-sessions/${paymentSessionId}/voids`, method: "GET", params }, options);
};
exports.listPaymentSessionVoids = listPaymentSessionVoids;
/**
* 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
*/
const getPaymentSessionVoid = (paymentSessionId, voidId, options) => {
return (0, cdpApiClient_js_1.cdpApiClient)({ url: `/v2/payment-sessions/${paymentSessionId}/voids/${voidId}`, method: "GET" }, options);
};
exports.getPaymentSessionVoid = getPaymentSessionVoid;
/**
* 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
*/
const refundPaymentSession = (paymentSessionId, createRefundRequest, options) => {
return (0, cdpApiClient_js_1.cdpApiClient)({
url: `/v2/payment-sessions/${paymentSessionId}/refunds`,
method: "POST",
headers: { "Content-Type": "application/json" },
data: createRefundRequest,
}, options);
};
exports.refundPaymentSession = refundPaymentSession;
/**
* 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
*/
const listPaymentSessionRefunds = (paymentSessionId, params, options) => {
return (0, cdpApiClient_js_1.cdpApiClient)({ url: `/v2/payment-sessions/${paymentSessionId}/refunds`, method: "GET", params }, options);
};
exports.listPaymentSessionRefunds = listPaymentSessionRefunds;
/**
* 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
*/
const getPaymentSessionRefund = (paymentSessionId, refundId, options) => {
return (0, cdpApiClient_js_1.cdpApiClient)({ url: `/v2/payment-sessions/${paymentSessionId}/refunds/${refundId}`, method: "GET" }, options);
};
exports.getPaymentSessionRefund = getPaymentSessionRefund;
//# sourceMappingURL=payment-sessions.js.map