{ "openapi": "3.1.0", "info": { "title": "Widget webhooks", "version": "1.0.0", "description": "Webhook events MoonPay sends to your configured endpoints for widget (Buy, Sell, Swap) integrations. Configure endpoints and event subscriptions in the [MoonPay dashboard](https://dashboard.moonpay.com/developers/#webhooks). All events are delivered as HTTP POST requests with a JSON body, signed with the `Moonpay-Signature` and `Moonpay-Signature-V2` headers. Delivery is at-least-once and unordered: duplicates can occur and events can arrive out of order, so handlers must be idempotent." }, "security": [], "webhooks": { "transaction_created": { "post": { "summary": "Buy transaction created", "description": "Sent when a customer creates a Buy transaction in the widget.", "operationId": "transaction_created", "parameters": [ { "$ref": "#/components/parameters/MoonpaySignature" }, { "$ref": "#/components/parameters/MoonpaySignatureV2" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "The event type.", "enum": ["transaction_created"] }, "data": { "$ref": "#/components/schemas/BuyTransaction" }, "externalCustomerId": { "type": ["string", "null"], "description": "An identifier associated with the customer, provided by you. Also present inside `data`." } }, "required": ["type", "data"] } } } }, "responses": { "200": { "description": "Return any 2xx status code within 5 seconds to acknowledge receipt. Non-2xx responses, timeouts and connection errors are retried with exponential backoff." } } } }, "transaction_updated": { "post": { "summary": "Buy transaction updated", "description": "Sent whenever a Buy transaction's status or details change.", "operationId": "transaction_updated", "parameters": [ { "$ref": "#/components/parameters/MoonpaySignature" }, { "$ref": "#/components/parameters/MoonpaySignatureV2" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "The event type.", "enum": ["transaction_updated"] }, "data": { "$ref": "#/components/schemas/BuyTransaction" }, "externalCustomerId": { "type": ["string", "null"], "description": "An identifier associated with the customer, provided by you. Also present inside `data`." } }, "required": ["type", "data"] } } } }, "responses": { "200": { "description": "Return any 2xx status code within 5 seconds to acknowledge receipt. Non-2xx responses, timeouts and connection errors are retried with exponential backoff." } } } }, "transaction_failed": { "post": { "summary": "Buy transaction failed", "description": "Sent when a Buy transaction fails.", "operationId": "transaction_failed", "parameters": [ { "$ref": "#/components/parameters/MoonpaySignature" }, { "$ref": "#/components/parameters/MoonpaySignatureV2" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "The event type.", "enum": ["transaction_failed"] }, "data": { "$ref": "#/components/schemas/BuyTransaction" }, "externalCustomerId": { "type": ["string", "null"], "description": "An identifier associated with the customer, provided by you. Also present inside `data`." } }, "required": ["type", "data"] } } } }, "responses": { "200": { "description": "Return any 2xx status code within 5 seconds to acknowledge receipt. Non-2xx responses, timeouts and connection errors are retried with exponential backoff." } } } }, "sell_transaction_created": { "post": { "summary": "Sell transaction created", "description": "Sent when a customer creates a Sell transaction in the widget.", "operationId": "sell_transaction_created", "parameters": [ { "$ref": "#/components/parameters/MoonpaySignature" }, { "$ref": "#/components/parameters/MoonpaySignatureV2" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "The event type.", "enum": ["sell_transaction_created"] }, "data": { "$ref": "#/components/schemas/SellTransaction" } }, "required": ["type", "data"] } } } }, "responses": { "200": { "description": "Return any 2xx status code within 5 seconds to acknowledge receipt. Non-2xx responses, timeouts and connection errors are retried with exponential backoff." } } } }, "sell_transaction_updated": { "post": { "summary": "Sell transaction updated", "description": "Sent whenever a Sell transaction's status or details change.", "operationId": "sell_transaction_updated", "parameters": [ { "$ref": "#/components/parameters/MoonpaySignature" }, { "$ref": "#/components/parameters/MoonpaySignatureV2" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "The event type.", "enum": ["sell_transaction_updated"] }, "data": { "$ref": "#/components/schemas/SellTransaction" } }, "required": ["type", "data"] } } } }, "responses": { "200": { "description": "Return any 2xx status code within 5 seconds to acknowledge receipt. Non-2xx responses, timeouts and connection errors are retried with exponential backoff." } } } }, "sell_transaction_failed": { "post": { "summary": "Sell transaction failed", "description": "Sent when a Sell transaction fails.", "operationId": "sell_transaction_failed", "parameters": [ { "$ref": "#/components/parameters/MoonpaySignature" }, { "$ref": "#/components/parameters/MoonpaySignatureV2" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "The event type.", "enum": ["sell_transaction_failed"] }, "data": { "$ref": "#/components/schemas/SellTransaction" } }, "required": ["type", "data"] } } } }, "responses": { "200": { "description": "Return any 2xx status code within 5 seconds to acknowledge receipt. Non-2xx responses, timeouts and connection errors are retried with exponential backoff." } } } }, "sell_transaction_requote_required": { "post": { "summary": "Sell transaction requote required", "description": "Sent when a Sell transaction requires a requote because the price moved before the customer's deposit was received. The transaction's `status` is `requoteRequired`. See the [requote webhooks guide](/widget/off-ramp/customization/requote-webhooks) for how to surface requotes in-app.", "operationId": "sell_transaction_requote_required", "parameters": [ { "$ref": "#/components/parameters/MoonpaySignature" }, { "$ref": "#/components/parameters/MoonpaySignatureV2" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "The event type.", "enum": ["sell_transaction_requote_required"] }, "data": { "$ref": "#/components/schemas/SellTransaction" } }, "required": ["type", "data"] } } } }, "responses": { "200": { "description": "Return any 2xx status code within 5 seconds to acknowledge receipt. Non-2xx responses, timeouts and connection errors are retried with exponential backoff." } } } }, "identity_check_updated": { "post": { "summary": "Identity check updated", "description": "Sent whenever the KYC status of a customer changes.", "operationId": "identity_check_updated", "parameters": [ { "$ref": "#/components/parameters/MoonpaySignature" }, { "$ref": "#/components/parameters/MoonpaySignatureV2" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "The event type.", "enum": ["identity_check_updated"] }, "data": { "$ref": "#/components/schemas/IdentityCheck" }, "externalCustomerId": { "type": ["string", "null"], "description": "An identifier associated with the customer, provided by you. Also present inside `data`." } }, "required": ["type", "data"] } } } }, "responses": { "200": { "description": "Return any 2xx status code within 5 seconds to acknowledge receipt. Non-2xx responses, timeouts and connection errors are retried with exponential backoff." } } } }, "virtual_account_status_updated": { "post": { "summary": "Virtual account status updated", "description": "Sent when the status of a virtual account changes.", "operationId": "virtual_account_status_updated", "parameters": [ { "$ref": "#/components/parameters/MoonpaySignature" }, { "$ref": "#/components/parameters/MoonpaySignatureV2" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "The event type.", "enum": ["virtual_account_status_updated"] }, "body": { "$ref": "#/components/schemas/VirtualAccountStatusUpdated" } }, "required": ["type", "body"] } } } }, "responses": { "200": { "description": "Return any 2xx status code within 5 seconds to acknowledge receipt. Non-2xx responses, timeouts and connection errors are retried with exponential backoff." } } } }, "virtual_account_transaction_status_updated": { "post": { "summary": "Virtual account transaction status updated", "description": "Sent when the status of a transaction within a virtual account changes.", "operationId": "virtual_account_transaction_status_updated", "parameters": [ { "$ref": "#/components/parameters/MoonpaySignature" }, { "$ref": "#/components/parameters/MoonpaySignatureV2" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "The event type.", "enum": ["virtual_account_transaction_status_updated"] }, "body": { "$ref": "#/components/schemas/VirtualAccountTransactionStatusUpdated" } }, "required": ["type", "body"] } } } }, "responses": { "200": { "description": "Return any 2xx status code within 5 seconds to acknowledge receipt. Non-2xx responses, timeouts and connection errors are retried with exponential backoff." } } } } }, "components": { "parameters": { "MoonpaySignature": { "name": "Moonpay-Signature", "in": "header", "required": true, "description": "Legacy signature: `t=,s=` where the signature is an HMAC-SHA256 of `.` keyed with the endpoint's signing secret. Prefer `Moonpay-Signature-V2`.", "schema": { "type": "string" } }, "MoonpaySignatureV2": { "name": "Moonpay-Signature-V2", "in": "header", "required": true, "description": "Signature to verify the event was sent by MoonPay: `t=,s=` where the signature is an HMAC-SHA256 of `.` keyed with your account's webhook API key. See [Request signing](/api-reference/widget/webhooks/signature).", "schema": { "type": "string" } } }, "schemas": { "BuyTransaction": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the transaction.", "example": "defb7c52-7bd3-422b-9052-374df50cc51a" }, "createdAt": { "type": "string", "description": "Time at which the object was created. Returned as an ISO 8601 string.", "example": "2024-02-17T18:24:45.206Z" }, "updatedAt": { "type": "string", "description": "Time at which the object was last updated. Returned as an ISO 8601 string.", "example": "2024-02-17T18:24:45.206Z" }, "quoteExpiresAt": { "type": ["string", "null"], "description": "Time at which the buy quote expires. Returned as an ISO 8601 string.", "example": "2024-02-17T18:54:45.206Z" }, "baseCurrencyAmount": { "type": "number", "description": "A positive number representing how much the customer wants to spend. The minimum amount is 20.", "example": 45.5 }, "quoteCurrencyAmount": { "type": "number", "description": "A positive number representing the amount of cryptocurrency the customer will receive. Set when the purchase of cryptocurrency has been executed.", "example": 0.0154 }, "feeAmount": { "type": "number", "description": "A positive number representing the fee for the transaction. It is added to baseCurrencyAmount, extraFeeAmount and networkFeeAmount when the customer's card is charged.", "example": 1.7 }, "extraFeeAmount": { "type": "number", "description": "A positive number representing your extra fee for the transaction. It is added to baseCurrencyAmount and feeAmount when the customer's card is charged.", "example": 0.43 }, "paymentMethod": { "$ref": "#/components/schemas/PaymentMethods" }, "networkFeeAmount": { "type": "number", "description": "A positive number representing the network fee for the transaction. It is added to baseCurrencyAmount, feeAmount and extraFeeAmount when the customer's card is charged.", "example": 2.37 }, "areFeesIncluded": { "type": "boolean", "description": "A boolean indicating whether baseCurrencyAmount includes or excludes the feeAmount, extraFeeAmount and networkFeeAmount.", "example": true }, "status": { "type": "string", "description": "The transaction's status.\nPossible values are `waitingPayment` (pending bank transfers where MoonPay is not in receipt), `pending` (transaction is in progress), `waitingAuthorization` (waiting for card approval, i.e. 3DS, bank side security), `failed` or `completed`.\n", "example": "completed", "enum": [ "waitingPayment", "pending", "waitingAuthorization", "failed", "completed" ] }, "failureReason": { "type": ["string", "null"], "description": "The transaction's failure reason. Set when transaction's status is failed.", "example": null }, "walletAddress": { "type": "string", "description": "The cryptocurrency wallet address the purchased funds will be sent to.", "example": "0xc216eD2D6c295579718dbd4a797845CdA70B3C36" }, "walletAddressTag": { "type": ["string", "null"], "description": "The secondary cryptocurrency wallet address identifier for coins such as EOS, XRP and XMR.", "example": null }, "cryptoTransactionId": { "type": ["string", "null"], "description": "The cryptocurrency transaction identifier representing the transfer to the customer's wallet. Set when the withdrawal has been executed.", "example": "0x6751c8fce2e0fb5d57bb4801b31b35a7160fa362e0c5703d44cfd508317ee2f8" }, "redirectUrl": { "type": ["string", "null"], "description": "The URL provided to you, when required, to which to redirect the customer as part of a redirect authentication flow.", "example": "https://api.moonpay.com/secure/url?transactionId=defb7c52-7bd3-422b-9052-374df50cc51a" }, "returnUrl": { "type": "string", "description": "The URL the customer is returned to after they authenticate or cancel their payment on the payment method's app or site. If you are using our widget implementation, this is always our transaction tracker page, which provides the customer with real-time information about their transaction.", "example": "https://buy.moonpay.com/transaction_receipt?transactionId=defb7c52-7bd3-422b-9052-374df50cc51a" }, "widgetRedirectUrl": { "type": ["string", "null"], "description": "An optional URL used in a widget implementation. It is passed to us by you in the query parameters, and we include it as a link on the transaction tracker page.", "example": null }, "eurRate": { "type": "number", "description": "The exchange rate between the transaction's base currency and Euro at the time of the transaction.", "example": 0.92432 }, "usdRate": { "type": "number", "description": "The exchange rate between the transaction's base currency and US Dollar at the time of the transaction.", "example": 1 }, "gbpRate": { "type": "number", "description": "The exchange rate between the transaction's base currency and British Pound at the time of the transaction.", "example": 0.79016 }, "currencyId": { "type": "string", "example": "8d305f63-1fd7-4e01-a220-8445e591aec4", "description": "The identifier of the cryptocurrency the customer wants to purchase." }, "currency": { "$ref": "#/components/schemas/CryptoCurrency" }, "baseCurrencyId": { "type": "string", "example": "edd81f1f-f735-4692-b410-6def107f17d2", "description": "The identifier of the fiat currency the customer wants to use for the transaction." }, "baseCurrency": { "$ref": "#/components/schemas/FiatCurrency" }, "customerId": { "type": "string", "description": "The identifier of the customer the transaction is associated with.", "example": "77cc1309-0058-4177-b170-8e9657fe12eb" }, "cardId": { "type": ["string", "null"], "description": "For token or card transactions, the identifier of the payment card used for this transaction.", "example": "0a7e23d8-6a52-44c7-b189-91b37bd13796" }, "bankAccountId": { "type": ["string", "null"], "description": "For bank transfer transactions, the identifier of the bank account used for this transaction.", "example": null }, "externalCustomerId": { "type": ["string", "null"], "description": "An identifier associated with the customer, provided by you." }, "externalTransactionId": { "type": ["string", "null"], "description": "An identifier associated with the transaction, provided by you." }, "country": { "type": "string", "description": "The customer's country. Returned as an ISO 3166-1 alpha-3 code.", "example": "GBR" }, "state": { "type": ["string", "null"], "description": "The customer's state, if the customer is from the USA. Returned as a two-letter code.", "example": null }, "isFromQuote": { "type": "boolean", "description": "Whether the transaction was created from a locked quote." }, "isRecurring": { "type": "boolean", "description": "Whether the transaction is part of a recurring buy." }, "isTicketPayment": { "type": "boolean", "description": "Whether the transaction is a ticket payment." }, "flow": { "type": "string", "description": "The transaction flow.", "examples": ["principal"] }, "bankTransferReference": { "type": ["string", "null"], "description": "For bank transfer transactions, the reference the customer must include with their transfer." }, "bankDepositInformation": { "type": ["object", "null"], "description": "For bank transfer transactions, the bank account details the customer must transfer fiat to." }, "feeAmountDiscount": { "type": ["number", "null"], "description": "Discount applied to the fee amount, if any." }, "extraFeeAmountDiscount": { "type": ["number", "null"], "description": "Discount applied to your extra fee, if any." }, "nftTransaction": { "type": ["object", "null"], "description": "Populated for NFT transactions only." }, "nftToken": { "type": ["object", "null"], "description": "The NFT token being purchased. Populated when `flow` is `nft`, otherwise `null`." }, "stages": { "type": "array", "description": "The four transaction stages and the status of each. Only present on `transaction_created` and `transaction_failed` events.", "items": { "$ref": "#/components/schemas/TransactionStage" } }, "cardType": { "type": ["string", "null"], "description": "For card transactions, how the card was provided.", "examples": ["card", "apple_pay", "google_pay"] }, "cardPaymentType": { "type": ["string", "null"], "description": "For card transactions, the card payment type.", "examples": ["credit", "debit"] } }, "description": "The Buy transaction object as delivered in webhook events. Matches the [Get Buy transaction](/api-reference/widget/getbuytransaction) response, plus webhook-only fields such as `stages`, `cardType` and `nftToken`." }, "SellTransaction": { "type": "object", "properties": { "id": { "type": "string", "example": "9020fd02-42ac-497f-8b5f-41fdf4dd0b1d", "description": "Unique identifier for the object." }, "createdAt": { "type": "string", "example": "2024-02-23T00:58:26.577Z", "description": "Time at which the object was created. Returned as an ISO 8601 string." }, "updatedAt": { "type": "string", "example": "2024-02-23T00:58:26.577Z", "description": "Time at which the object was last updated. Returned as an ISO 8601 string." }, "quoteExpiresAt": { "type": ["string", "null"], "description": "Time at which the sell quote expires. Returned as an ISO 8601 string.", "example": "2024-02-23T01:28:26.577Z" }, "baseCurrencyAmount": { "type": "number", "example": 0.575, "description": "A positive number representing how much the customer wants to sell." }, "quoteCurrencyAmount": { "type": "number", "example": 1521.11, "description": "A positive number representing the amount of cryptocurrency the customer will receive. Set when the purchase of cryptocurrency has been executed." }, "feeAmount": { "type": "number", "example": 15.36, "description": "A positive number representing the fee for the transaction." }, "extraFeeAmount": { "type": "number", "example": 0, "description": "A positive number representing your extra fee for the transaction." }, "status": { "type": "string", "example": "completed", "description": "The transaction's status.", "enum": [ "waitingForDeposit", "pending", "failed", "completed", "requoteRequired" ] }, "failureReason": { "type": ["string", "null"], "description": "The transaction's failure reason. Set when transaction's status is failed.", "example": null }, "refundWalletAddress": { "type": "string", "description": "A wallet address at which the customer can receive cryptocurrency. In case we cannot process the sale of the customer's cryptocurrency, we will return the cryptocurrency to this wallet address. Might be empty", "example": "" }, "depositHash": { "type": ["string", "null"], "description": "The cryptocurrency transaction identifier representing the transfer from the customer's wallet to MoonPay's wallet. Set when the deposit has been executed and received.", "example": "0x0e13c1c9d8b542a1888e63e6d5871a2199893a0f2851c9353120b7e18fce1802" }, "widgetRedirectUrl": { "type": ["string", "null"], "description": "An optional URL used in a widget implementation. It is passed to us by you in the query parameters, and we include it as a link on the transaction tracker page.", "example": null }, "payoutMethod": { "type": "string", "example": "credit_debit_card", "description": "The transaction's payout method.", "enum": [ "ach_bank_transfer", "credit_debit_card", "paypal", "gbp_bank_transfer", "sepa_bank_transfer" ] }, "eurRate": { "type": "number", "description": "The exchange rate between the transaction's base currency and Euro at the time of the transaction.", "example": 1 }, "usdRate": { "type": "number", "description": "The exchange rate between the transaction's base currency and US Dollar at the time of the transaction.", "example": 1.08193 }, "gbpRate": { "type": "number", "description": "The exchange rate between the transaction's base currency and British Pound at the time of the transaction.", "example": 0.85501 }, "quoteCurrencyId": { "type": "string", "example": "71435a8d-211c-4664-a59e-2a5361a6c5a7", "description": "The identifier of the fiat the customer wants to get." }, "quoteCurrency": { "$ref": "#/components/schemas/FiatCurrency" }, "baseCurrencyId": { "type": "string", "example": "8d305f63-1fd7-4e01-a220-8445e591aec4", "description": "The identifier of the crypto currency the customer wants to sell." }, "baseCurrency": { "$ref": "#/components/schemas/CryptoCurrency" }, "customerId": { "type": "string", "example": "3b97352d-a9c2-4786-afe7-e7d74e0a8ad7", "description": "The identifier of the customer the transaction is associated with." }, "bankAccountId": { "type": ["string", "null"], "example": "ee0e649f-a072-4cdb-96ce-a1ea393eac1e", "description": "The identifier of the bank account used for this transaction." }, "externalCustomerId": { "type": ["string", "null"], "example": null, "description": "An identifier associated with the customer, provided by you." }, "externalTransactionId": { "type": ["string", "null"], "example": null, "description": "An identifier associated with the transaction, provided by you." }, "flow": { "type": "string", "description": "The transaction flow.", "examples": ["principal"] }, "accountId": { "type": "string", "description": "Identifier of your MoonPay account." }, "cardId": { "type": ["string", "null"], "description": "Identifier of the payout card, when paying out to a card." }, "depositWalletId": { "type": ["string", "null"], "description": "Identifier of the MoonPay wallet the customer deposits crypto to. Assigned once the deposit wallet is created." }, "depositWallet": { "anyOf": [ { "$ref": "#/components/schemas/DepositWallet" }, { "type": "null" } ], "description": "The MoonPay wallet the customer deposits crypto to. Populated once the deposit wallet is created." }, "refundWalletAddressRequestedAt": { "type": ["string", "null"], "description": "Time at which a refund wallet address was requested from the customer, as an ISO 8601 string.", "format": "date-time" }, "refundHash": { "type": ["string", "null"], "description": "Blockchain transaction hash of the refund, if the deposit was refunded." }, "confirmations": { "type": ["number", "null"], "description": "Number of blockchain confirmations received for the deposit." }, "quoteExpiredEmailSentAt": { "type": ["string", "null"], "description": "Time at which a quote-expired email was sent to the customer, as an ISO 8601 string.", "format": "date-time" }, "refundApprovalStatus": { "type": ["string", "null"], "description": "Approval status of a refund, if one was initiated." }, "cancelledById": { "type": ["string", "null"], "description": "Identifier of the operator that cancelled the transaction, if it was cancelled." }, "blockedById": { "type": ["string", "null"], "description": "Identifier of the operator that blocked the transaction, if it was blocked." }, "depositMatchedManuallyById": { "type": ["string", "null"], "description": "Identifier of the operator that manually matched the deposit, if it was matched manually." }, "createdById": { "type": ["string", "null"], "description": "Identifier of the operator that created the transaction, if created manually." }, "incomingCustomerCryptoDepositId": { "type": ["string", "null"], "description": "Identifier of the matched incoming crypto deposit." }, "integratedSellDepositInfo": { "type": ["object", "null"], "description": "Deposit details for integrated (semi-automatic) sell flows." }, "country": { "type": ["string", "null"], "description": "ISO 3166-1 alpha-3 country code of the customer." }, "state": { "type": ["string", "null"], "description": "US state code of the customer, if applicable." } }, "description": "The Sell transaction object as delivered in webhook events. Matches the [Get Sell transaction](/api-reference/widget/getselltransaction) response, plus webhook-only fields such as `depositWallet`, `country` and `state`." }, "IdentityCheck": { "type": "object", "description": "The identity check object as delivered in webhook events.", "properties": { "id": { "type": "string", "description": "Unique identifier of the identity check." }, "createdAt": { "type": "string", "description": "Time at which the check was created, as an ISO 8601 string.", "format": "date-time" }, "updatedAt": { "type": "string", "description": "Time at which the check was last updated, as an ISO 8601 string.", "format": "date-time" }, "status": { "type": "string", "description": "The customer's KYC status.", "enum": ["initiated", "pending", "completed"] }, "result": { "type": ["string", "null"], "description": "Whether the customer passed KYC.", "enum": ["clear", "rejected", null] }, "rejectType": { "type": ["string", "null"], "description": "The rejection type, when rejected.", "enum": ["final", "retry", "level2Request", "level3Request", null] }, "rejectLabels": { "type": ["array", "null"], "description": "KYC failure reasons, when rejected.", "items": { "type": "string", "enum": [ "Poor Image Quality", "Document Incomplete", "Expired Document", "ID Not Supported", "Data Mismatch", "Address Mismatch", "Other" ] } }, "resultDescription": { "type": ["string", "null"], "description": "Human-readable description of the KYC failure reason." }, "level": { "type": "number", "description": "Know Your Customer (KYC) level of the customer." }, "rejections": { "type": "number", "description": "Number of KYC rejections for this customer." }, "escalationReasons": { "type": ["array", "null"], "description": "Whether the customer's KYC was escalated for review and why, e.g. `kyc_review`.", "items": { "type": "string" } }, "customerId": { "type": "string", "description": "Identifier of the customer the check is associated with." }, "externalCustomerId": { "type": ["string", "null"], "description": "An identifier associated with the customer, provided by you." } } }, "VirtualAccountStatusUpdated": { "type": "object", "properties": { "virtualAccountId": { "type": "string", "description": "Unique identifier (UUID) of the virtual account." }, "externalCustomerId": { "type": ["string", "null"], "description": "An identifier associated with the customer, provided by you." }, "status": { "type": "string", "description": "Current status of the virtual account.", "enum": ["pending", "completed", "failed"] }, "timestamp": { "type": "integer", "description": "Unix timestamp in milliseconds at which the event was triggered." } }, "required": ["virtualAccountId", "status", "timestamp"] }, "VirtualAccountTransactionStatusUpdated": { "type": "object", "properties": { "virtualAccountId": { "type": "string", "description": "Unique identifier (UUID) of the virtual account." }, "externalCustomerId": { "type": ["string", "null"], "description": "An identifier associated with the customer, provided by you." }, "transactionId": { "type": "string", "description": "Unique identifier (UUID) of the transaction." }, "status": { "type": "string", "description": "Current status of the transaction.", "enum": ["Pending", "Completed", "Failed"] }, "timestamp": { "type": "integer", "description": "Unix timestamp in milliseconds at which the event was triggered." } }, "required": ["virtualAccountId", "transactionId", "status", "timestamp"] }, "TransactionStage": { "type": "object", "description": "One of the four transaction stages shown in the widget.", "properties": { "stage": { "type": "string", "description": "The stage of the transaction.", "enum": [ "stage_one_ordering", "stage_two_verification", "stage_three_processing", "stage_four_delivery" ] }, "status": { "type": "string", "description": "The status of this stage.", "enum": ["not_started", "in_progress", "success", "failed"] }, "actions": { "type": "array", "description": "Actions the customer may need to complete for this stage to progress, e.g. retrying identity verification.", "items": { "type": "object", "properties": { "type": { "type": "string", "description": "The action type." }, "url": { "type": "string", "description": "URL the customer should visit to complete the action." } } } }, "failureReason": { "type": ["string", "null"], "description": "Reason this stage failed, if it did." } } }, "DepositWallet": { "type": "object", "description": "A MoonPay-managed deposit wallet for a Sell transaction.", "properties": { "id": { "type": "string", "description": "Unique identifier of the deposit wallet." }, "createdAt": { "type": "string", "description": "Time at which the wallet was created, as an ISO 8601 string.", "format": "date-time" }, "updatedAt": { "type": "string", "description": "Time at which the wallet was last updated, as an ISO 8601 string.", "format": "date-time" }, "walletAddress": { "type": "string", "description": "The deposit address the customer sends crypto to." }, "walletAddressTag": { "type": ["string", "null"], "description": "Secondary address identifier (memo/tag), for currencies that require one." }, "customerId": { "type": "string", "description": "Identifier of the customer the wallet was created for." }, "currencyId": { "type": "string", "description": "Identifier of the currency the wallet accepts." }, "btcLegacyAddress": { "type": ["string", "null"], "description": "Legacy-format Bitcoin address, for Bitcoin wallets." }, "type": { "type": "string", "description": "The wallet provider type." }, "encryptedPrivateKey": { "type": ["string", "null"], "description": "Always `null`." } } }, "CryptoCurrency": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the currency.", "example": "aaefa32f-161b-42c8-8115-debcbf3d6a2d" }, "createdAt": { "type": "string", "description": "Time at which the object was created. Returned as an ISO 8601 string.", "example": "2019-05-17T18:24:45.206Z" }, "updatedAt": { "type": "string", "description": "Time at which the object was last updated. Returned as an ISO 8601 string.", "example": "2019-05-17T18:24:45.206Z" }, "type": { "type": "string", "enum": ["crypto"], "description": "Always `crypto`", "example": "crypto" }, "name": { "type": "string", "description": "The currency's name.", "example": "USD Coin (ERC-20)" }, "code": { "type": "string", "description": "The currency's code.", "example": "usdc" }, "precision": { "type": "number", "description": "The currency's precision (number of digits after decimal point).", "example": 2 }, "minBuyAmount": { "type": ["number", "null"], "description": "Represents the minimum amount of cryptocurrency you can buy.", "example": 30 }, "maxBuyAmount": { "type": ["number", "null"], "description": "Represents the maximum amount of cryptocurrency you can buy.", "example": 1000 }, "minSellAmount": { "type": ["number", "null"], "description": "The minimum amount of cryptocurrency you can sell.", "example": 15 }, "maxSellAmount": { "type": ["number", "null"], "description": "The maximum amount of cryptocurrency you can sell.", "example": 100000 }, "addressRegex": { "type": "string", "description": "A regular expression which you can test against your end user's wallet addresses.", "example": "^(0x)[0-9A-Fa-f]{40}$" }, "testnetAddressRegex": { "type": "string", "description": "A regular expression which you can test against your end user's testnet wallet addresses.", "example": "^(0x)[0-9A-Fa-f]{40}$" }, "supportsAddressTag": { "type": "boolean", "description": "Whether the currency supports address tags.", "example": false }, "addressTagRegex": { "type": ["string", "null"], "description": "A regular expression which you can test against a wallet address tag. Defined only if the currency supports address tags.", "example": null }, "supportsTestMode": { "type": "boolean", "description": "Whether the currency supports test mode.", "example": true }, "isSuspended": { "type": "boolean", "description": "Whether purchases for this currency are suspended. If the currency is suspended, exchange rates may not be available and it is not possible to create a transaction with this currency.", "example": false }, "isSupportedInUs": { "type": "boolean", "description": "Whether purchases for this currency are supported in the US.", "example": true }, "isSellSupported": { "type": "boolean", "description": "Whether sales for this currency are supported.", "example": true }, "notAllowedUSStates": { "type": "array", "items": { "type": "string", "enum": [ "AL", "AK", "AZ", "AR", "AS", "CA", "CO", "CT", "DC", "DE", "FL", "GA", "GU", "HI", "ID", "IL", "IN", "IA", "KS", "KY", "LA", "MA", "MD", "ME", "MI", "MN", "MO", "MP", "MS", "MT", "NE", "NH", "NV", "NH", "NJ", "NM", "NY", "NC", "ND", "OH", "OK", "OR", "PA", "PR", "RI", "SC", "SD", "TN", "TX", "TT", "UT", "VT", "VA", "VI", "WA", "WV", "WI", "WY" ] }, "description": "A list with all the US states for this currency that are not supported.", "example": ["LA", "VI"] }, "notAllowedCountries": { "type": "array", "items": { "type": "string" }, "description": "A list with all the ISO 3166-1 alpha-2 country codes for this currency that are not supported.", "example": ["CA"] }, "metadata": { "type": "object", "description": "Additional metadata for the currency.", "properties": { "contractAddress": { "type": ["string", "null"], "description": "Unique contract address where the token smart contract is hosted.", "example": "0x0000000000000000000000000000000000000000" }, "chainId": { "type": ["string", "null"], "description": "ID used to identify different EVM compatible chains.", "example": "1" }, "networkCode": { "type": "string", "description": "Name of the cryptocurrency", "example": "ethereum" } } } } }, "FiatCurrency": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the currency.", "example": "6f424585-8936-4eb1-b01e-443fb306d1f5" }, "createdAt": { "type": "string", "description": "Time at which the object was created. Returned as an ISO 8601 string.", "example": "2019-05-17T18:24:45.206Z" }, "updatedAt": { "type": "string", "description": "Time at which the object was last updated. Returned as an ISO 8601 string.", "example": "2019-05-17T18:24:45.206Z" }, "type": { "type": "string", "enum": ["fiat"], "description": "Always `fiat`", "example": "fiat" }, "name": { "type": "string", "description": "The currency's name.", "example": "Pound Sterling" }, "code": { "type": "string", "description": "The currency's code.", "example": "gbp" }, "precision": { "type": "number", "description": "The currency's precision (number of digits after decimal point).", "example": 2 }, "minBuyAmount": { "type": ["number", "null"], "description": "Represents the minimum transaction buy amount when using this currency as a base currency.", "example": 30 }, "maxBuyAmount": { "type": ["number", "null"], "description": "Represents the maximum transaction buy amount when using this currency as a base currency.", "example": 9000 }, "isSellSupported": { "type": "boolean", "description": "Whether sales for this currency are supported.", "example": true } } }, "PaymentMethods": { "type": "string", "example": "credit_debit_card", "enum": [ "ach_bank_transfer", "credit_debit_card", "paypal", "gbp_bank_transfer", "gbp_open_banking_payment", "pix_instant_payment", "sepa_bank_transfer" ], "description": "The transaction's payment method." } } } }