@moonpay/platform-protocol 0.3.0 → 1.0.2

package/dist/api/index.d.cts

@@ -0,0 +1,466 @@
+/**
+ * A fiat currency or crypto token
+ */
+type Asset = {
+    /**
+     * A fiat or crypto currency code.
+     *
+     * **Fiat**
+     * Fiat codes are represented as [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217) codes.
+     *
+     * Currently only `USD` is supported.
+     *
+     * **Crypto**
+     * For crypto currency codes, see [supported currencies](https://dev.moonpay.com/docs/list-of-supported-cryptocurrencies).
+     *
+     * Examples: `BTC` `SOL` `ETH` `USDC_BASE` `USDC_SOL`
+     */
+    code: string;
+    /**
+     * The human-readable name
+     */
+    name?: string;
+    /**
+     * The number of supported decimal places
+     */
+    precision?: number;
+};
+type AssetBase = {
+    /**
+     * A fiat or crypto currency code.
+     *
+     * **Fiat**
+     * Fiat codes are represented as [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217) codes.
+     *
+     * Currently only `USD` is supported.
+     *
+     * **Crypto**
+     * For crypto currency codes, see [supported currencies](https://dev.moonpay.com/docs/list-of-supported-cryptocurrencies).
+     *
+     * Examples: `BTC` `SOL` `ETH` `USDC_BASE` `USDC_SOL`
+     */
+    code: string;
+};
+type CreateSessionTokenRequestBody = {
+    /**
+     * A unique identifier for the customer from your system.
+     */
+    externalCustomerId?: string;
+    /**
+     * The IP address of the user's device to ensure the integrity of the session. Both IPv4 and IPv6 values are supported.
+     */
+    deviceIp: IPv4Address | IPv6Address;
+    /**
+     * The customer's email address. Must be a valid email. If provided, `phoneNumber` must also be provided.
+     */
+    email?: string;
+    /**
+     * The customer's phone number in E.164 format. If provided, `email` must also be provided.
+     */
+    phoneNumber?: string;
+};
+type CreateSessionTokenResponse = {
+    /**
+     * An opaque session token used to set up a connection on your frontend. This token is single-use and must be generated each time the customer visits your app.
+     *
+     * Token expires 24 hours after issuance.
+     */
+    sessionToken: string;
+};
+type Fees = {
+    /**
+     * Network fees (in fiat) for the transaction.
+     */
+    network?: MonetaryFeeAmount;
+    /**
+     * MoonPay fees (in fiat) for the transaction.
+     */
+    moonpay?: MonetaryFeeAmount;
+    /**
+     * Ecosystem fees (in fiat) for the transaction, if applicable.
+     */
+    ecosystem?: MonetaryFeeAmount;
+    /**
+     * Partner fees (in fiat) for the transaction, if applicable. Deprecated: use `fees.ecosystem` instead. This field will be removed in a future release.
+     * @deprecated
+     */
+    partner?: MonetaryFeeAmount;
+};
+type GetQuoteBody = {
+    /**
+     * Source asset in fiat. Amount can be set in `source` or `destination`.
+     */
+    source: {
+        /**
+         * The currency or token being spent
+         */
+        asset: AssetBase;
+        /**
+         * A stringified amount, which can include decimals.
+         */
+        amount?: string;
+    };
+    /**
+     * Destination asset in crypto. Amount can be set in `destination` or `source`.
+     */
+    destination: {
+        asset: AssetBase;
+        /**
+         * The amount being received, if known
+         */
+        amount?: string;
+    };
+    /**
+     * Wallet address and optional tag where the crypto will be sent. Required for the quote to be executable.
+     */
+    wallet?: Wallet;
+    /**
+     * Payment method for the transaction. Required for the quote to be executable.
+     */
+    paymentMethod?: QuotePaymentMethod;
+};
+/**
+ * Quote for a fiat-to-crypto buy. Contains locked rate, fees, expiry, and signature for payment execution.
+ */
+type GetQuoteResponse = {
+    /**
+     * Source side of the quote: amount and asset (fiat currency) you send.
+     */
+    source: {
+        /**
+         * A stringified amount, which can include decimals.
+         */
+        amount: string;
+        /**
+         * The currency or token being spent
+         */
+        asset: Asset;
+    };
+    /**
+     * Destination side of the quote: amount and asset (cryptocurrency) the customer receives.
+     */
+    destination: {
+        /**
+         * A stringified amount, which can include decimals.
+         */
+        amount: string;
+        asset: Asset;
+    };
+    /**
+     * Breakdown of network, MoonPay, and ecosystem fees.
+     */
+    fees: Fees;
+    /**
+     * Wallet address and optional tag where the crypto will be sent. Null when not provided.
+     */
+    wallet: Wallet | null;
+    /**
+     * The payment method used for the quote.
+     */
+    paymentMethod: QuotePaymentMethod | null;
+    limits: QuoteLimits | null;
+    /**
+     * An [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) timestamp of when the quote expires.
+     */
+    expiresAt: string;
+    /**
+     * Whether the quote can be executed. Only `executable` quotes can be used to initiate payment frames.
+     */
+    executable: boolean;
+    /**
+     * The rate used to convert fiat <-> crypto, expressed as the crypto value of one unit of fiat.
+     */
+    exchangeRate: string;
+    /**
+     * Disclosures the partner must render verbatim before the customer can complete the transaction. Empty when no disclosure is required for the customer's geography, payment method, and asset combination.
+     */
+    paymentDisclosures: Array<PaymentDisclosure>;
+    /**
+     * An opaque token representing the quote to initiate payment frames.
+     */
+    signature: string;
+};
+type IPv4Address = string;
+type IPv6Address = string;
+type LimitWithAsset = {
+    /**
+     * A stringified amount, which can include decimals.
+     */
+    amount: string;
+    asset: AssetBase;
+};
+type MonetaryFeeAmount = {
+    /**
+     * The amount of fees in fiat.
+     */
+    amount: string;
+    /**
+     * The fiat currency used to pay the fees.
+     */
+    asset: AssetBase;
+};
+type MoonPayCorePaginationInfo = {
+    /**
+     * The cursor to use as the starting point for the next page of results.
+     */
+    nextCursor: string | null;
+};
+/**
+ * The card network brand.
+ */
+type MoonPayPaymentsCardBrand = 'visa' | 'mastercard' | 'maestro' | 'american_express' | 'other';
+/**
+ * The type of card: credit, debit, or unknown.
+ */
+type MoonPayPaymentsCardType = 'credit' | 'debit' | 'unknown';
+type MoonPayPaymentsListPaymentMethodsResponse = {
+    /**
+     * List of available payment method configurations
+     */
+    paymentMethodConfigs?: Array<MoonPayPaymentsPaymentMethod>;
+    /**
+     * List of stored payment methods available for the customer
+     */
+    paymentMethods?: Array<MoonPayPaymentsStoredPaymentMethod>;
+};
+type MoonPayPaymentsPaymentMethod = {
+    type: PaymentMethodType;
+    /**
+     * Details of how the payment method can be used.
+     */
+    capabilities: MoonPayPaymentsPaymentMethodCapabilities;
+    availability: MoonPayPaymentsPaymentMethodAvailability;
+};
+type MoonPayPaymentsPaymentMethodAvailability = {
+    /**
+     * Whether the payment method is available
+     */
+    active: boolean;
+    /**
+     * If the payment method is not available, reasons explaining why.
+     */
+    reasons?: Array<string>;
+};
+type MoonPayPaymentsPaymentMethodCapabilities = {
+    /**
+     * [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217) codes of fiat currencies supported by this payment method.
+     */
+    supportedCurrencies: Array<string>;
+    /**
+     * Transaction types supported by this payment method.
+     */
+    supportedTransactionTypes: Array<string>;
+    /**
+     * Whether this payment method can be deleted.
+     */
+    allowsDeletion: boolean;
+    /**
+     * Whether this payment method requires the MoonPay widget to complete the payment flow.
+     */
+    requiresWidget: boolean;
+};
+type MoonPayPaymentsStoredCardPaymentMethod = MoonPayPaymentsStoredPaymentMethodBase & {
+    cardType: MoonPayPaymentsCardType;
+    /**
+     * The card network brand
+     */
+    brand: MoonPayPaymentsCardBrand;
+    /**
+     * Last 4 digits of the card number
+     */
+    last4: string;
+    /**
+     * Expiration month as 2-digit string
+     */
+    expirationMonth: string;
+    /**
+     * Expiration year as 4-digit string
+     */
+    expirationYear: string;
+    /**
+     * Current availability of this stored card
+     */
+    availability: MoonPayPaymentsPaymentMethodAvailability;
+};
+/**
+ * A stored payment method.
+ */
+type MoonPayPaymentsStoredPaymentMethod = MoonPayPaymentsStoredPaymentMethodBase | MoonPayPaymentsStoredCardPaymentMethod;
+type MoonPayPaymentsStoredPaymentMethodBase = {
+    /**
+     * Unique identifier for the stored payment method
+     */
+    id: string;
+    type: PaymentMethodType;
+};
+/**
+ * A payment disclosure that the partner must render verbatim before the customer can complete the transaction.
+ */
+type PaymentDisclosure = {
+    /**
+     * Stable identifier of the disclosure. Each id maps to one specific piece of text. The full list of ids and their canonical text is published in the developer documentation.
+     */
+    id: string;
+    /**
+     * Version of the disclosure text. Bumped whenever the canonical wording for this `id` changes. Partners that receive an unknown `(id, version)` pair should fall back to a conservative disclosure and alert their integration team.
+     */
+    version: string;
+};
+type PaymentMethodType = 'apple_pay' | 'card' | 'ach' | 'fps' | 'fps_open_banking' | 'google_pay' | 'sepa' | 'sepa_open_banking' | 'pix' | 'paypal' | 'venmo' | 'revolut_pay' | 'moonpay_balance' | 'interac';
+type QuoteLimitEntry = {
+    /**
+     * The maximum amount.
+     */
+    limit: LimitWithAsset;
+    /**
+     * The remaining amount.
+     */
+    remaining: LimitWithAsset;
+};
+/**
+ * Limits applicable to the quote.
+ */
+type QuoteLimits = {
+    /**
+     * The daily limit.
+     */
+    daily?: QuoteLimitEntry;
+    /**
+     * The monthly limit.
+     */
+    monthly?: QuoteLimitEntry;
+    /**
+     * The yearly limit.
+     */
+    yearly?: QuoteLimitEntry;
+};
+type QuotePaymentMethod = {
+    type: PaymentMethodType;
+    /**
+     * Unique identifier of the payment method. Used to identify the specific card when type is card.
+     */
+    id?: string;
+};
+/**
+ * A stage in the transaction lifecycle
+ */
+type Stage = {
+    kind?: StageKind;
+    /**
+     * The human-readable name of the stage.
+     */
+    name?: string;
+    status?: StageStatus;
+    /**
+     * A developer-friendly message if the status is `failed`
+     */
+    failureReason?: string | null;
+};
+/**
+ * The stages in a transaction lifecycle.
+ */
+type StageKind = 'ordering' | 'waiting_payment' | 'waiting_authentication' | 'verification' | 'processing' | 'delivery' | 'crypto_hold';
+/**
+ * The status of a transaction stage.
+ */
+type StageStatus = 'not_started' | 'in_progress' | 'success' | 'failed';
+type TermsAttestation = {
+    /**
+     * The MoonPay ID of the terms attestation.
+     */
+    id: string;
+    /**
+     * Your identifier for the end customer who accepted MoonPay's terms.
+     */
+    externalCustomerId: string;
+    /**
+     * An [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) formatted string indicating when the attestation was recorded.
+     */
+    attestedAt: string;
+};
+type Transaction = {
+    /**
+     * The MoonPay ID of the transaction.
+     */
+    id: string;
+    /**
+     * An [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) timestamp of when the transaction was created.
+     */
+    createdAt: string;
+    /**
+     * An [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) timestamp of when the transaction was last updated.
+     */
+    updatedAt: string;
+    status: TransactionStatus;
+    /**
+     * Source amount and asset (fiat currency) the customer paid.
+     */
+    source: {
+        /**
+         * A stringified amount, which can include decimals.
+         */
+        amount: string;
+        /**
+         * The currency or token being spent
+         */
+        asset: AssetBase;
+    };
+    /**
+     * Destination amount and asset (cryptocurrency) the customer receives.
+     */
+    destination: {
+        /**
+         * A stringified amount, which can include decimals.
+         */
+        amount: string;
+        asset: AssetBase;
+    };
+    /**
+     * Details of fees for the transaction.
+     */
+    fees: Fees;
+    /**
+     * The wallet used for the transaction.
+     */
+    wallet: Wallet;
+    customer: TransactionCustomer;
+    paymentMethod?: TransactionPaymentMethod;
+};
+type TransactionCustomer = {
+    /**
+     * The MoonPay ID of the customer associated with the transaction.
+     */
+    id: string;
+};
+type TransactionPaymentMethod = {
+    type: PaymentMethodType;
+};
+/**
+ * The status of a transaction.
+ *
+ * - `completed`: The transaction is finalized and assets were delivered.
+ * - `failed`: The transaction failed. No payment was executed and funds were not transferred.
+ * - `pending`: The transaction was created and payment is accepted. The transfer is in progress.
+ */
+type TransactionStatus = 'completed' | 'failed' | 'pending';
+/**
+ * Transaction with lifecycle stages showing step-by-step progress.
+ */
+type TransactionWithStages = Transaction & {
+    /**
+     * Details of the stages in the transaction lifecycle.
+     */
+    stages?: Array<Stage>;
+};
+type Wallet = {
+    /**
+     * The wallet address used for the transaction.
+     */
+    address: string;
+    /**
+     * An optional memo or destination tag (used by some blockchains such as XRP or XLM).
+     */
+    tag?: string;
+};
+
+export type { Asset, AssetBase, CreateSessionTokenRequestBody, CreateSessionTokenResponse as CreateSessionTokenReturnType, Fees, GetQuoteBody as GetQuoteParams, LimitWithAsset, MoonPayPaymentsListPaymentMethodsResponse as ListPaymentMethodsResponse, MonetaryFeeAmount, MoonPayCorePaginationInfo as PaginationInfo, MoonPayPaymentsPaymentMethodAvailability as PaymentMethodAvailability, MoonPayPaymentsPaymentMethodCapabilities as PaymentMethodCapabilities, MoonPayPaymentsPaymentMethod as PaymentMethodConfig, PaymentMethodType, GetQuoteResponse as Quote, QuoteLimitEntry, QuoteLimits, QuotePaymentMethod, Stage, StageKind, StageStatus, MoonPayPaymentsStoredCardPaymentMethod as StoredCardPaymentMethod, MoonPayPaymentsStoredPaymentMethod as StoredPaymentMethod, TermsAttestation, Transaction, TransactionCustomer, TransactionPaymentMethod, TransactionStatus, TransactionWithStages, Wallet };