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 an ssh tunnel, for example Localhost.run.

To run the tunnel, 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
ssh -R 80:localhost:8080 $(uuidgen)@ssh.localhost.run

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

Connect to http://a94bca6d-05e8-49a7-b22d-08012366bfe8-d763fbc1.localhost.run
{"domain": "a94bca6d-05e8-49a7-b22d-08012366bfe8-d763fbc1.localhost.run", "listen_port": 80, "status": "success", "message": "Connect to http://a94bca6d-05e8-49a7-b22d-08012366bfe8-d763fbc1.localhost.run"}

Note the value of the forwarding address (in the example above, http://a94bca6d-05e8-49a7-b22d-08012366bfe8-d763fbc1.localhost.run), as that is your public-facing URL to be used in this example. The tunnel supports HTTPs, when needed just replace http:// with https:// in the forwarding address.

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 tunnel forwarding address 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://a94bca6d-05e8-49a7-b22d-08012366bfe8-d763fbc1.localhost.run",
    "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 local server 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 local server 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 23 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.