A webhook notification is sent whenever a transaction is completed, whether successfully or unsuccessfully. In case of an error, the webhook will include the errorData which will contain an error code. Please note the error codes on this page are just examples.

The webhook notifications are sent in a generic envelope. The envelope will carry the data related to the notification as well as the info on which type of notification this is. The "data" part of the payload differs, but is always the same for each "type". E.g. if the "type" in the notification is "PAYMENT_METHOD", the "data" object will have the corresponding structure that will always be the same for every notification that has "type":"PAYMENT_METHOD".

Below is an example of the general notification envelope. Details of each "data" object are addressed in the following chapters.

{
    "id": "173921f7-0953-4f28-b60b-b1a5e758ec9d",//Unique Identifier to identify this notification
    "type": "CAAS" | "PAYMENT_METHOD" | "REFUND" | "CAAS_BLOCKCHAIN",
    "at": 1724075850, //timestamp in epoch seconds
    "data": {
      //unique data structure that corresponds to the "type"
     }
}

Transaction Notifications

Notification related to transaction status

For this notification, "type" will always be "CAAS" and the notifications are related to the Buy and Sell flow. The data will contain the info of the payment provider ("data.providerId") as well as the related transaction ID ("data.transactionId"). It will also contain a "data.type" field of its own, where the values can be BUY, SELL or ORDER_TRACKING. This specifies the transaction flow to which the notification is related to. Another field is the "data.metadata". This field contains metadata related to the flow and the structure of the "data.metadata" depends on the "data.type" value, as shown in the examples below:

data.type == BUY and data.type == SELL

Below is an example for both BUY and SELL flows

{
    "id": "173921f7-0953-4f28-b60b-b1a5e758ec9d",
    "type": "CAAS", //for buy/sell will ALWAYS be CAAS
    "at": 1724075850,
    "data": {
        "type": "BUY", //enum, specifies that this is a BUY transaction
        "providerId": "654987321", //this is payment provider id, will be obtained from Coinme
        "transactionId": "321324131", // unique transaction identifier, partnerTransactionId from create transaction requests
        "metadata": {
            "orderStatus": "COMPLETED", //can be CREATED, PENDING, BLOCKCHAIN_ACCEPTED, or CONFIRMED
            "blockchainData": {
                "targetWalletAddress": "string",
                "blockchainTransactionId": "string",
                "blockchainMemo": "string",
                "currency": "string",
                "chain": "string",
                "refundWalletAddress": "string",
                "sourceWalletAddress": "string"
              }
        },
        "errorData": {
            "code": "123-213-S1",
            "message": "Description"
        } //if metadata.orderStatus == FAILED, this will be populated
    }
}

{
    "id": "173921f7-0953-4f28-b60b-b1a5e758ec9d",
    "type": "CAAS", //for buy/sell will ALWAYS be CAAS
    "at": 1724075850,
    "data": {
        "type": "SELL", //enum, specifies that this is a SELL transaction
        "providerId": "654987321", //this is payment provider id, will be obtained from Coinme
        "transactionId": "321324131", // unique transaction identifier, partnerTransactionId from create transaction requests
        "metadata": {
            "orderStatus": "COMPLETED", //can be CREATED, PENDING, BLOCKCHAIN_ACCEPTED, or CONFIRMED
            "blockchainData": {
                "targetWalletAddress": "string",
                "blockchainTransactionId": "string",
                "blockchainMemo": "string",
                "currency": "string",
                "chain": "string",
                "refundWalletAddress": "string",
                "sourceWalletAddress": "string"
              }
        },
        "errorData": {
            "code": "123-213-S1",
            "message": "Description"
        } //if metadata.orderStatus == FAILED, this will be populated
    }
}

orderStatus definitions

A special case is when "data.type" is set to ORDER TRACKING. Order tracking is supported only for payment providers that require the end user to go a physical site (e.g. an ATM or a kiosk) to complete the fiat part of the transaction using physical currency (aka. cash). In case of Sell that would mean pick up the cash, in case of Buy that would mean hand in the cash. Certain payment providers provide feedback when this step of the process is completed and in that case, the notification of"type" == "CAAS" with"data.type" == "ORDER_TRACKING"_ is sent. The format of this notification is identical to the Buy and Sell (since "type" == "CAAS") with the exception of the "data.metadata" field, as shown in the example below:

{
    "id": "173921f7-0953-4f28-b60b-b1a5e758ec9d",
    "type": "CAAS", //for buy/sell will ALWAYS be CAAS
    "at": 1724075850,
    "data": {
        "type": "ORDER_TRACKING", //enum, specifies that this is related to tracking the fiat settlement when taking place in a physical site
        "providerId": "654987321", //this is payment provider id, will be obtained from Coinme
        "transactionId": "321324131", // unique transaction identifier, partnerTransactionId from create transaction requests
        "metadata": {
            "orderType": "BUY" | "SELL" //specifies if the tracking is related to a buy or a sell
            "providerTransactionId":"12313" // ID of the transaction in the payment provider's system
            "providerTransactionRef":"432423" //Reference to the transaction the user had to provide on the physical site to complete the transaction
            "providerTransactionStatus": "COMPLETED" | "EXPIRED" //COMPLETED specifies the user completed the transaction, EXPIRED means the user took too long to complete this step and the transaction expired in the payment provider's system
            "trackingStateDescription" : "description of the current state of the tracking"
        },
        "errorData": null //no error data available for this step of the process
    }
}

Notifications related to external wallet refund

In case the partner is executing a sell transaction and using the option to settle the crypto part of the transaction on an external wallet (also called "external sell") instead of Coinme's custody wallet (aka. sending crypto funds from an external wallet) a dedicated notification type will be sent in case of a failure. This notification is related to refunding the crypto Coinme received from an external wallet as part of the sell transaction process.

Please note: The refund is performed only if an error occurs in the transaction process after the crypto funds were received from an external wallet (aka. the transaction on the blockchain went through). In such a case, the refund is issued (if the refund wallet address was provided when the transaction was initiated). This results in 2 notifications - first one being about failed transaction ("type" == "CAAS" and "type.data" == "SELL") and the second one about the refund status.

The notification about the refund status will have the filed "type" == "REFUND" and will have a dedicated "data" object, as shown below:

{
    "id": "173921f7-0953-4f28-b60b-b1a5e758ec9d",
    "type": "REFUND", //indicates that this is a notification related to external sell refunds
    "at": 1724075850,
    "data": {
        "providerId": "654987321", //this is payment provider id, will be obtained from Coinme
        "transactionId": "321324131", // unique transaction identifier, partnerTransactionId from create transaction requests
        "status": "SUCCESS" | "FAIL", // specifies if the refund was successful or not
        "metadata": {
            "blockchainTransactionId": "txHash131", //if refund was successful, this is blockchain tx id of refund
            "amount": "12.32", //amount refunded
            "currency": "ETH", //currency
            "walletAddress": "walletAddress" //wallet address where the refund was executed
        },
        "errorData": {
            "code": "123-213-S1",
            "message": "Description"
        } //if status == FAIL, this will be populated
    }
}

Payment Method Notifications

Notifications related to payment methods

If using a digital payment provider via Coinme, the user will have to add a payment method (aka. credit/debit card) which will be used in the scope of executing buys and sells via a digital payment provider. The flow for adding a payment method is asynchronous, just like Buys and Sells, and these notification serves as information about any changes to the status of the payment method during this process.

If payment method is being added, webhooks can be sent after that action as well - if payment method addition gets declined, following notification will be sent:

{
    "id": "173921f7-0953-4f28-b60b-b1a5e758ec9d",//Unique Identifier to identify this notification
    "type": "PAYMENT_METHOD",
    "at": 1724075850, //timestamp in epoch seconds
    "data": {
        "status": "DECLINED" | "STAGED", //enum, other values are CREATED, VERIFIED, DELETED though notifications for those statuses are currently not being sent
        "paymentMethodId": "654987321", //id of payment method for which notification is sent
        "accountId": "321324131", //the customerId
        "errorCode": "123-213-S1" //will be populated only if "status":"DECLINED"
    }
}

In case an error occurs during the addition of a payment method, that payment method will be declined. The notification will have "status" == "DECLINED" and will also have an "errorCode" populated which uniquely identifies the reason for the failure.

When adding a payment method, Coinme also offers the option to verify a payment method via microtransactions. If this option is used, Coinme will execute a small number of microtransactions (immediately reverted) against the card the user entered. The user will have to verify those amounts by checking their bank account and inputing the microtransaction values via a Coinme endpoint. In such a case, when the payment method is created via an API call, after the microtransactions have been successfully executed, the status of the payment method will switch from "CREATED" to "STAGED", indicating that the user may now attempt to verify the payment method. When this happens, a notification is issued with the "status" == "STAGED"

Custodial Wallet Notifications

Notifications related to end user custodial wallets

1-Wallet Creation Notifications

Coinme’s Custodial Wallet (CaaS) Stack allows partners to automatically generate and manage custodial wallets for their end users.

When this feature is enabled for your partner integration (please contact your Coinme Account Manager to enable it), custodial wallet addresses are created for each supported cryptocurrency once a customer is successfully onboarded via the POST /services/customeronboarding endpoint.

After a successful customer creation, Coinme generates custodial wallet addresses for all supported assets on behalf of that customer. For each generated wallet, a webhook notification is sent to your configured webhook URL.

Example Payload:

{
  "id": "1d282094-9a89-4f55-8492-5e5468350bbf",
  "type": "WALLET",
  "data": {
    "operation": "WALLET_CREATED",
    "customerId": "1288809346943684608",
    "walletAddress": "0x809212ad3cFd1bB86eF51B3C392850da9FB39690",
    "assetId": "USDT",
    "chain": "ETH"
  },
  "at": "2025-09-26T10:28:28Z"
}

2-Deposit Notifications

Once wallets are created, any confirmed deposit to those wallets—whether received on-chain or internally via Coinme’s custodial ledger—will trigger a webhook notification.

{
  "id": "3de582f8-0da2-4484-b056-485ce31e8c35",
  "type": "CAAS_BLOCKCHAIN",
  "data": {
    "type": "RECEIVE",
    "status": "COMPLETED",
    "partnerTransactionId": "1288822976133861376",
    "customerId": "1288809346943684608",
    "metadata": {
      "sourceAddress": "0x0e941BAE5379ca90b91aCf5bCcda11504cb52093",
      "destinationAddress": "0x809212ad3cFd1bB86eF51B3C392850da9FB39690",
      "asset": {
        "amount": "10000000",
        "currency": "USDT"
      },
      "blockchainTransctionId": "0xd1bfec2cc8328469980499422dd2d1ceca7d614204e2cbe510cb24ec7da3d9f4"
    }
  },
  "at": "2025-09-26T11:22:22Z"
}

Error Codes

General System errors

Buy and Sell process errors

Custody wallet errors

External Sell partner REST call errors

Blockchain processing errors

Digital payments errors

Crypto Send process errors