Circle APIs Documentation Portal

Welcome! Here you will find guides and reference docs to help you integrate with Circle APIs and get up and running in no time.
Read the Docs
Get Started

Circle Payments API Quickstart 💨

Get up and running with the Circle Payments API just after a few minutes with the following steps.

:one+: Get an API key :lock+:

The Circle Payments API uses API keys as the mechanism to authenticate client requests. The API key must be set in the Authorization header of the request sent from your backend server. The format of the header is Bearer secret-key-value.

Learn more about authenticating API calls here.

To obtain an API key for the sandbox environment, simply create an account and generate a new key in settings - it only takes a few seconds.


Get an API key

Once you have generated your API key, record it in a secure place.

:two+: Install the sample application :computer+:

We have built a sample web application to demonstrate the use of Circle Payments API. You can clone the Github repository, configure the app and run it locally.

If you don't already, make sure you have npm and yarn installed.

# Clone the sample app Github repository
git clone https://github.com/circlefin/payments-sample-app.git

# Change into sample app folder
cd payments-sample-app

# Create a .env file and configure the base url for api calls
echo BASE_URL=https://api-sandbox.circle.com > .env

# Install the dependencies
yarn install

# Run the sample app locally
yarn dev
The sample application should now be running at: http://localhost:3011.

Take the API key you generated on step 1, and enter it on the settings tab on the top right corner of the sample application.

:three+: Accept your first card payment :credit-card+:

On the sample application, click on the Charge Flow button under the "Example UI implementation" section.

Use one of the test card numbers available on the sandbox environment. For example, 4007400000000007.

Type in an amount, pick a value for CVV and expiry date, and add some billing information details.

Submit the payment creation request by clicking on the Make Payment button.

:tada+: Congrats, you processed your first card payment that settles in USDC! You should see a payment identifier on the resulting screen, something like Payment id: 81855279-b53d-4119-9f1e-5d0af00f0c24.

:four+: Check the status of your card payment :moneybag+:

Now make an API call to retrieve the status of your card payment. Use your API key from step 1 and the payment identifier you obtained on step 3.

# Replace ${YOUR_API_KEY} with the API key obtained on step 1
# Replace ${PAYMENT_ID} with the payment id obtained on step 3
curl -H 'Accept: application/json' \
  -H "Authorization: Bearer ${YOUR_API_KEY}" \
  -X GET --url https://api-sandbox.circle.com/v1/payments/${PAYMENT_ID}

You should receive a response such as:

{
  "data": {
    "id": "81855279-b53d-4119-9f1e-5d0af00f0c24",
    "refId": "75a9a26d-0ce5-4307-91b9-e3bdb91981bc",
    "merchantId": "ff71551d-ae18-492d-baf1-d9205e20e0bf",
    "merchantAccountNumber": "1000002584",
    "amount": {
      "amount": "5.00",
      "currency": "USD"
    },
    "source": {
      "id": "1fa990d9-fd12-400c-bc7d-e54a428f7570",
      "type": "card"
    },
    "description": "Payment",
    "createDate": 1583830582515,
    "status": "confirmed",
    "fees": {
      "amount": "0.10",
      "currency": "USD"
    }
  }
}

:tada+: You are all done!

:five+: Like what you see? Keep going!

By accepting a card payment that settles in USDC, you have just touched the tip of the iceberg of Circle APIs.

Make sure you read the longer form guide on accepting payments online. Also make sure you check the rest of the documentation - a few starting points are suggested below.

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

Updated 15 days ago



Circle Payments API Quickstart 💨


Suggested Edits are limited on API Reference Pages

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