Merchant notifications

API notifications allow you to subscribe to updates for your merchant tools. Notifications are sent as HTTP POST requests (webhooks) to a notification endpoint.

Notifications are part of the Coinbase API and provide many useful features for merchants using Coinbase. These include notifications for:

  • Order payment confirmation (wallet:orders:paid)
  • Order mispayment (wallet:orders:mispaid)
  • Automated merhant payouts (wallet:merchant-payouts:created)

These can be useful in various integrations, such as to mark an order as “paid” in your own database when you’ve received a payment.

For API v1 users: Notifications are significantly different from Merhant Callbacks used in Coinbase API v1. Legacy callbacks can still be used but if you’re building integrations for API v2, we recommend that you use notifications.

Setting up merchant notifications

You can set up Merchant Notifications similarly to regular Coinbase API Notifications. Merchant Notifications adhere to the same re-try schedule and method of securing your notifications.

If you don’t have an API key set up for your account, you can alternatively set notifications in your merchant settings. Unlike API key, this integration option will only send you merchant related notifications, including types:

  • wallet:orders:paid
  • wallet:orders:mispaid
  • wallet:merchant-payouts:created

If your system needs order specific notification endpoints, you also set an order or checkout specific endpoint when creating them via API. More information can be found in the API reference for orders and checkouts.

Example Notifications

Order Paid Example

When an order receives a payment for the correct amount, a notification with type wallet:orders:paid is sent out. For more information about different notification fields, see API reference.

{
  "id": "cbb019fe-e04d-5b65-8321-95ecc6353c1b",
  "type": "wallet:orders:paid",
  "data": {
    "resource": {
      "id": "1f03b664-4c19-53d3-af34-62d6bad031b9",
      "code": "NXH22AZT",
      "type": "order",
      "name": "Good vibes",
      "description": "Positive thoughts and good vibes.",
      "amount": {
        "amount": "0.02",
        "currency": "USD"
      },
      "receipt_url": "https:\/\/www.coinbase.com\/orders\/582cc9caaad4e55e36817599197c5efd\/receipt",
      "resource": "order",
      "resource_path": "\/v2\/orders\/1f03b664-4c19-53d3-af34-62d6bad031b9",
      "status": "paid",
      "bitcoin_amount": {
        "amount": "0.00006100",
        "currency": "BTC"
      },
      "payout_amount": null,
      "bitcoin_address": "1KcGmmoyYrLkQGHuR48yxGFZiEt3F5x6Rh",
      "refund_address": null,
      "bitcoin_uri": "bitcoin:1KcGmmoyYrLkQGHuR48yxGFZiEt3F5x6Rh?amount=0.000061&r=https:\/\/www.coinbase.com\/r\/5644f61bb750bc5fab0001ac",
      "paid_at": "2015-11-12T20:27:45Z",
      "mispaid_at": null,
      "expires_at": "2015-11-12T20:42:07Z",
      "metadata": {},
      "created_at": "2015-11-12T20:27:07Z",
      "updated_at": "2015-11-12T20:27:45Z",
      "customer_info": null,
      "transaction": {
        "id": "fd8e4e97-5df4-5fb4-8357-8182fe3d03ef",
        "resource": "transaction",
        "resource_path": "\/v2\/accounts\/81180219-027c-5d68-b38e-e7f3d0a4a5ae\/transactions\/fd8e4e97-5df4-5fb4-8357-8182fe3d03ef"
      },
      "mispayments": [],
      "refunds": []
    }
  },
  "user": {
    "id": "fc1c8832-e5f4-5871-9405-6b143949b5ac",
    "resource": "user",
    "resource_path": "\/v2\/users\/fc1c8832-e5f4-5871-9405-6b143949b5ac"
  },
  "account": {
    "id": "81180219-027c-5d68-b38e-e7f3d0a4a5ae",
    "resource": "account",
    "resource_path": "\/v2\/accounts\/81180219-027c-5d68-b38e-e7f3d0a4a5ae"
  },
  "delivery_attempts": 0,
  "created_at": "2015-11-12T20:27:45Z",
  "resource": "notification",
  "resource_path": "\/v2\/notifications\/cbb019fe-e04d-5b65-8321-95ecc6353c1b"
}

Order Mispayment Example

When an order receives a mispayment (incorrect amount), a notification with type wallet:orders:mispaid is sent out. For more information about different notification fields, see API reference.

{
  "id": "c303dfd8-9127-5863-9b90-49917fcef9b5",
  "type": "wallet:orders:mispaid",
  "data": {
    "resource": {
      "id": "210fec4f-44f7-50f6-b3ec-f4cddac57029",
      "code": "7UWSY29R",
      "type": "order",
      "name": "Good vibes",
      "description": "Positive thoughts and good vibes.",
      "amount": {
        "amount": "1.00",
        "currency": "USD"
      },
      "receipt_url": "https:\/\/www.coinbase.com\/orders\/69a076d7c242d3777e3861425cad6105\/receipt",
      "resource": "order",
      "resource_path": "\/v2\/orders\/210fec4f-44f7-50f6-b3ec-f4cddac57029",
      "status": "mispaid",
      "bitcoin_amount": {
        "amount": "0.00242400",
        "currency": "BTC"
      },
      "payout_amount": null,
      "bitcoin_address": "1FDKRYFxKvp1jg2PLxKpj6YkxXnBHbQNjH",
      "refund_address": null,
      "bitcoin_uri": "bitcoin:1FDKRYFxKvp1jg2PLxKpj6YkxXnBHbQNjH?amount=0.002424&r=https:\/\/www.coinbase.com\/r\/5644fa744e607635db000083",
      "paid_at": null,
      "mispaid_at": "2015-11-12T20:46:38Z",
      "expires_at": "2015-11-12T21:00:40Z",
      "metadata": {},
      "created_at": "2015-11-12T20:45:40Z",
      "updated_at": "2015-11-12T20:46:38Z",
      "customer_info": null,
      "transaction": {
        "id": "79147800-608a-5b80-b647-c8fa27769107",
        "resource": "transaction",
        "resource_path": "\/v2\/accounts\/81180219-027c-5d68-b38e-e7f3d0a4a5ae\/transactions\/79147800-608a-5b80-b647-c8fa27769107"
      },
      "mispayments": [
        {
          "id": "56b1dc24-0bfc-52ec-84be-555d23d528dc",
          "amount": {
            "amount": "0.00022400",
            "currency": "BTC"
          },
          "native_amount": {
            "amount": "0.07",
            "currency": "USD"
          },
          "refund_address": null,
          "transaction": {
            "id": "79147800-608a-5b80-b647-c8fa27769107",
            "resource": "transaction",
            "resource_path": "\/v2\/accounts\/81180219-027c-5d68-b38e-e7f3d0a4a5ae\/transactions\/79147800-608a-5b80-b647-c8fa27769107"
          },
          "refund_transaction": null,
          "created_at": "2015-11-12T20:46:38Z",
          "updated_at": "2015-11-12T20:46:38Z"
        }
      ],
      "refunds": []
    }
  },
  "user": {
    "id": "fc1c8832-e5f4-5871-9405-6b143949b5ac",
    "resource": "user",
    "resource_path": "\/v2\/users\/fc1c8832-e5f4-5871-9405-6b143949b5ac"
  },
  "account": {
    "id": "81180219-027c-5d68-b38e-e7f3d0a4a5ae",
    "resource": "account",
    "resource_path": "\/v2\/accounts\/81180219-027c-5d68-b38e-e7f3d0a4a5ae"
  },
  "delivery_attempts": 0,
  "created_at": "2015-11-12T20:46:38Z",
  "resource": "notification",
  "resource_path": "\/v2\/notifications\/c303dfd8-9127-5863-9b90-49917fcef9b5"
}

Bitcoin Transaction Confirmations

Bitcoin transactions usually arrive within a few seconds, but can take anywhere from 10 minutes to 1 hour to become 100% confirmed in the blockchain (bitcoin’s public ledger system). While this potential delay may seem challenging, Coinbase has several measures in place to eliminate the effect on merchants.

When Coinbase sends an order notification with a type of wallet:orders:paid, and you have instant-exchange enabled, it is safe to assume at this point that the payout is guaranteed by Coinbase. Even if the associated payment transaction does not confirm, Coinbase will always pay out an order after sending a wallet:orders:paid notification.

Typically, Coinbase sends the notification within 1-2 seconds of the bitcoin transaction arriving. If we feel the transaction is at a higher risk for being double spent, we may delay sending the callback until we can be sure the transaction will be confirmed.