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.

Post-Payments Processing

Checking the Status of Your Card Payment

After you successfully process a payment, you have two options for learning about the status of that payment.

One option is to expose a subscriber endpoint on your side, and subscribe to notifications. Once a payment changes status, we will invoke your subscriber endpoint with the appropriate details. Check our guide on notifications for more details.

As an alternative, you can learn more about the status of a payment by simply polling for its status using the retrieve payments endpoint.

Below you can see an API request that retrieves the status of a specific card payment based on the card payment id.

# Replace ${YOUR_API_KEY} with the your API key
# Replace ${PAYMENT_ID} with the payment id you are interested in
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 like 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": "paid",
    "fees": {
      "amount": "0.10",
      "currency": "USD"
    }
  }
}

Card Payments Settlement

On the sandbox environment it takes between 5 and 10 minutes for a card payment to settle.

In the live environment, Circle typically processes settlement for all card transactions 3 or 4 business days after the date the transaction was authorized. At that point, a lump sum containing the proceeds from all applicable card transactions is tokenized into USDC and credited to your Circle digital wallet.

Once a settlement lands on your account, your master wallet balance will be credited with the appropriate amount. You can confirm your master wallet balance by using the balances endpoint in the following way.

# Replace ${YOUR_API_KEY} with your API key
curl -H 'Accept: application/json' \
  -H "Authorization: Bearer ${YOUR_API_KEY}" \
  -X GET --url https://api-sandbox.circle.com/v1/balances

You should receive a response like below.

{
  "data":[
    {
      "available":[
        {
          "amount":"140100.50",
          "currency":"USD"
        }
      ],
      "unsettled":[
      ]
    }
  ]
}

Updated 4 months ago


Post-Payments Processing


Suggested Edits are limited on API Reference Pages

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