Card Payments Quickstart

Get started with the Circle Payments API and accept your first card payment that settles in USDC!

1. Get an API key

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.

2. Install the sample application

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.

📘

NPM and Yarn

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.

📘

Enter Your API Key

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.

3. Accept your first card payment

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, real card numbers are not accepted in the sandbox environment.

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.

🎉 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.

4. Check the status of your card payment

Now make an API call to retrieve the status of your card payment using the get payment endpoint. 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}
/** 
 * See installation instructions at 
 * https://developers.circle.com/developer/docs/circle-sdk
 */
import { Circle, CircleEnvironments } from "@circle-fin/circle-sdk";

const circle = new Circle(
    '<your-api-key>',
    CircleEnvironments.sandbox      // API base url
);

async function checkCardPaymentStatus() {
    const paymentId = '${PAYMENT_ID}'
    const resp = await circle.payments.getPayment(paymentId);

    console.log(resp.data);
}
checkCardPaymentStatus();

You should receive a response such as below.

{
  "data": {
    "id": "81855279-b53d-4119-9f1e-5d0af00f0c24",
    "type": "payment",
    "merchantId": "ff71551d-ae18-492d-baf1-d9205e20e0bf",
    "merchantWalletId": "1000002584",
    "amount": {
      "amount": "5.00",
      "currency": "USD"
    },
    "source": {
      "id": "1fa990d9-fd12-400c-bc7d-e54a428f7570",
      "type": "card"
    },
    "description": "Payment",
    "createDate": 1583830582515,
    "trackingRef": "20674453824672941243272",
    "status": "confirmed",
    "fees": {
      "amount": "0.10",
      "currency": "USD"
    }
  }
}

🎉 You are all done!

Your payment will eventually change its status from confirmed to paid - at that point you have funds in your account available for use.

5. 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. Check how to subscribe to notifications on changes in payments status. Also make sure you check the rest of the documentation - a few starting points are suggested below.

6. 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!