Circle APIs Documentation

Learn how to integrate with Circle APIs to accept traditional and stablecoin payments, embed digital wallets into your product or service, or power your internet marketplace.

✨ Notifications Quickstart

You can easily receive notifications every time the status of any of your payments changes. This quickstart guide helps you quickly configure a notification subscriber endpoint.

1. Expose a subscriber endpoint

In order to receive notifications on changes in payments status, you will need to expose a publicly accessible subscriber endpoint on your side. That endpoint must be capable of handling POST requests over https.

To quickly expose an endpoint for testing, we have provided the code for a sample HTTP server as part of our sample payments application repository on Github. If you haven't already, follow these steps to download the sample payments app source code.

Once you have retrieved the sample code from Github, run the following commands to start the HTTP server containing a sample subscriber endpoint:

# Change into the sample HTTP server folder
cd payments-sample-app/devtools/node/

# Ensure you have all dependencies
yarn install

# Start the sample HTTP server on 127.0.0.1:8080
node httpserver.js 127.0.0.1 8080

You should see a message saying the HTTP server is starting on the desired port.

As this is only a sample server, the easiest way to expose this endpoint externally is to use a tool like ngrok. Download ngrok - you can extract it to the same folder as the sample HTTP server code. You will have to create an account with ngrok to obtain and configure your auth token.
Pretty much any ssh tunnel can be used, if ngrok does not work for you. Another alternative would be to use http://localhost.run which does not require download.

Once you have downloaded ngrok and configured your account, execute the following command on a separate shell.

# Expose your local sample HTTP server externally
# Use the same port you used on the previous step
./ngrok http 8080

You should see a status message that looks like the following:

ngrok by @inconshreveable

Session Status                online
Account                       John Doe (Plan: Free)
Version                       2.3.35
Region                        United States (us)
Web Interface                 http://127.0.0.1:4041
Forwarding                    http://ab12.ngrok.io -> http://localhost:8080
Forwarding                    https://ab12.ngrok.io -> http://localhost:8080

Connections                   ttl     opn     rt1     rt5     p50     p90
                              0       0       0.00    0.00    0.00    0.00

Note the value of the https forwarding address (in the example above, https://ab12.ngrok.io), as that is your public-facing URL to be used in this example.

2. Subscribe to payments status notifications

Now you need to register your public endpoint as a subscriber to payments status notifications. Do that by running the following command on a separate shell. If you haven't already, follow these steps to obtain your API key.

# Replace ${YOUR_API_KEY} with your API key
# Replace ${SUBSCRIBER_ENDPOINT_URL} with the ngrok URL from the previous step
curl -H 'Accept: application/json' \
  -H 'Content-type: application/json' \
  -H "Authorization: Bearer ${YOUR_API_KEY}" \
  -d "{\"endpoint\": \"${SUBSCRIBER_ENDPOINT_URL}\"}" \
  -X POST --url https://api-sandbox.circle.com/v1/notifications/subscriptions

You should receive a response like the following.

{
  "data":{
    "endpoint":"https://ab12.ngrok.io",
    "subscriptionDetails":[
      {
        "url":"arn:aws:sns:us-east-1:908968368384:sandbox_platform-notifications-topic:a1197c8f-0be7-4fa5-a1cd-fcf42d49522c",
        "status":"pending"
      },
      {
        "url":"arn:aws:sns:us-west-2:908968368384:sandbox_platform-notifications-topic:e535d7a3-5938-4e43-b84b-89bca7364688",
        "status":"pending"
      }
    ]
  }
}

Most importantly, at the same time you will receive a request on your ngrok shell confirming the subscription with a body like the following.

{
  "Type" : "SubscriptionConfirmation",
  "MessageId" : "ddbdcdcf-d36a-45b5-927c-da25b9b009ae",
  "Token" : "2336412f37fb687f5d51e6e2425f004aed7b7526d5fae41bc257a0d80532a6820258bf77eb25b90453b863450713a2a5a4250696d725a306ef39962b5b543752c9003e0841c0e61253fd6c517a94edebe44f36c5fe4ba131c8ea5f6f42a43f97f6e1865505e2f29f79a62f89e18f97e03a0dd5d982a7578c8d6e21154163f2d6aae523cff25557f9bc21b2503d413006",
  "TopicArn" : "arn:aws:sns:us-west-2:908968368384:sandbox_platform-notifications-topic",
  "Message" : "You have chosen to subscribe to the topic arn:aws:sns:us-west-2:908968368384:sandbox_platform-notifications-topic.\nTo confirm the subscription, visit the SubscribeURL included in this message.",
  "SubscribeURL" : "https://sns.us-west-2.amazonaws.com/?Action=ConfirmSubscription&TopicArn=arn:aws:sns:us-west-2:908968368384:sandbox_platform-notifications-topic&Token=2336412f37fb687f5d51e6e2425f004aed7b7526d5fae41bc257a0d80532a6820258bf77eb25b90453b863450713a2a5a4250696d725a306ef39962b5b543752c9003e0841c0e61253fd6c517a94edebe44f36c5fe4ba131c8ea5f6f42a43f97f6e1865505e2f29f79a62f89e18f97e03a0dd5d982a7578c8d6e21154163f2d6aae523cff25557f9bc21b2503d413006",
  "Timestamp" : "2020-04-11T20:50:16.324Z",
  "SignatureVersion" : "1",
  "Signature" : "kBr9z/ysQrr0ldowHY4lThkOA+dwyjcsyx7NwkbTkgEKG4N61BSSEA+43aYQEB/Ml09hclybvyjyRKWYOjaxQgbUXWmyWrCQ7vY93WYhuGvOqZxAMPiDiILxLs6/KtOxneKVvzfpK4abLrYyTTA+z/dQ52h9L8eoiSKSW81e4clfYBTJkGmuAPKFC08FvEAVT89VikPp68mBf4CctPv3Em0b4J1VvDhAB21B2LekgUmwUE0aE7fUbsF3XsKGQd/fDshLOJasQEuXSqdB5X7LITBA8r24FY+wCjwm8oR3VI9IMy21fUC6wMgoFIVZHW1KxzpEkMCSe7R1ySdNIru8SQ==",
  "SigningCertURL" : "https://sns.us-west-2.amazonaws.com/SimpleNotificationService-a86cb10b4e1f29c941702d737128f7b6.pem"
}

At this stage you have a sample local environment that is ready to receive notifications on payments status changes.

🚧

You can only add one subscriber endpoint per account (API key).

🚧

If a customer does not verify the topic ARN when confirming subscriptions, they open themselves up to accepting messages from arbitrary sns topics. They should verify that the topic arn matches the following regular expression: '^arn:aws:sns:.*:908968368384:(sandbox|prod)_platform-notifications-topic$'. Please see how verification is done in the sample HTTP server

3. Initiate a Payment Flow to Receive a Notification

To observe a notification message on the status of a payment, initiate a card payment - for example by following the Payments API Quickstart guide for card payments.

Once you process a successful payment, you should see a notification message on your ngrok shell that looks like the following.

{
  "Type" : "Notification",
  "MessageId" : "05dd4857-b93f-5a6c-a230-1f444c7e017b",
  "TopicArn" : "arn:aws:sns:us-east-1:908968368384:sandbox_platform-notifications-topic",
  "Message" : "{
    \"clientId\":\"ef25859e-4842-4b16-a3bd-cbe531e15b85\",
    \"notificationType\":\"payments\",
    \"version\":1,
    \"customAttributes\":{
      \"clientId\":\"ef25859e-4842-4b16-a3bd-cbe531e15b85\"
    },
    \"payment\": {
      \"id\":\"354fdbc7-9892-4e3e-b461-0a5b2015761d\",
      \"type\":\"payment\",
      \"merchantId\":\"ef25859e-4842-4b16-a3bd-cbe531e15b85\",
      \"merchantWalletId\":\"1000004841\",
      \"source\":{
        \"id\":\"2a8862f8-530b-4bc5-b6cf-88883310026b\",
        \"type\":\"card\"
      },
      \"description\":\"Payment\",
      \"amount\":{
        \"amount\":\"0.01\",
        \"currency\":\"USD\"
      },
      \"status\":\"confirmed\",
      \"createDate\":\"2020-04-17T18:18:38.838Z\"
    }
  }",
  "Timestamp" : "2020-04-17T18:18:41.531Z",
  "SignatureVersion" : "1",
  "Signature" : "b6lp6siDD1R4NZ8aPR5AcNua3GinP9Ol3PVfgCM6DtwA20O/f30s2EZU0IgexoeF0r2eP+rOpHZAL8pT5Tk/cjvCaEQ5Kck55k3vlNWqcgY2B116Gc5ujmIfOaC+oJBBU8GvCXtRzodN6JvrnNQzy00KzQ2vXyrXBs3kOLB5HwCVVxPM+7a4J2NT7SVCsca/GH+ffD35VH9TkDkZI6gDRbrT2Ac3TTnNum8s4vo1yzqkABsfFFgyqrFLqC3KeNrtOA3qDMQlvIjA9xsA05SamRegpa4vvvK6V++yCKnDG86v8yKUBgeBWCBhpL3U9mYQYQUzzXbUlXlXs9ShT62Rjg==",
  "SigningCertURL" : "https://sns.us-east-1.amazonaws.com/SimpleNotificationService-a86cb10b4e1f29c941702d737128f7b6.pem",
  "UnsubscribeURL" : "https://sns.us-east-1.amazonaws.com/?Action=Unsubscribe&SubscriptionArn=arn:aws:sns:us-east-1:908968368384:sandbox_platform-notifications-topic:8735fb3c-e8fc-4a73-a225-cb2852f570e0",
  "MessageAttributes" : {
    "clientId" : {
      "Type":"String",
      "Value":"ef25859e-4842-4b16-a3bd-cbe531e15b85"
    }
  }
}

Congratulations, you have received your first notification on a payment! 🎉

4. Ready for the next step?

If you are in advanced stages of experimenting with our APIs and want to plan moving to production, please start by applying for a business account and subsequently reach out to sales. We'll be happy to walk you through to the next steps.

We can't wait to see what you are going to build!

Updated 18 days ago


✨ Notifications Quickstart


Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.