This quickstart guide helps you quickly configure a notification subscriber endpoint that enables you to easily receive notifications every time the status of a resource changes. This guide will focus on the payment resource, but is applicable to any of the resources mentioned in Circle API Notifications.

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 both HEAD and 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.

📘
When creating a subscription, the endpoint you supply will be verified with an initial HEAD request. Please make sure the endpoint handles this request and returns a successful (2xx) response.

# 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"
}

🚧
The above body will be returned in a plain text format, so please be sure you're not expecting a JSON content type.

To complete the subscription process, you will need to visit the SubscribeURL from this response. Until you make a request to this URL, no additional messages will be sent to the endpoint.

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

🚧
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

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

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 Circle 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!