Quickstart: Receive stablecoin payins

Accept USDC on your site or app using Managed Payments stablecoin payins. You create a payment intent, share the deposit address, and Circle links the onchain payment to your intent. The steps use a continuous payment intent: the default pattern for a stable receive address per account.

The alternative Quickstart: Crypto Deposits walkthrough covers a transient payment intent instead (amount and time window set on create). Use that guide when you want a one-time, expiring checkout-style intent.

Prerequisites

Before you start, ensure you have:

Aligned with Circle on your Managed Payments onboarding model (Direct or Intermediary).
Completed Managed Payments onboarding with Circle and obtained API credentials. The cURL examples use the sandbox host api-sandbox.circle.com.
Roles that allow creating and reading payment intents and payments in your setup. Circle assigns roles during onboarding.
Subaccounts or any structure your setup requires so each intent ties to the right merchant or segment. See Managed Payments and the Digital Asset Accounts API if you create accounts first.
(Optional) A webhook receiver or queue to handle payment intent and payment events. See Set up a webhook endpoint.
(Optional) For an end-to-end test, a payer wallet with USDC and native gas on the chain you set on the intent (for example Sepolia ETH when the intent uses an Ethereum test chain).

Sequence diagram

Continuous payins use settlement currency and chain on create; you may see active instead of pending when the address is ready.

Steps

Set up payment intent to pay with stablecoin
Acquire blockchain address customer will pay to
Customer pays
Receive payment

1. Pay with stablecoin

When the customer confirms they want to pay with USDC on Ethereum, send a request to create a payment intent. In a continuous intent, you specify settlement currency and chain. No fixed charge amount is set on create. The required fields differ by Circle entity. Select the tab for the Circle entity that books your payins.

Circle LLC (US)
Circle Singapore (CIRCLE_SG)

Create a payment intent:

curl --location --request POST 'https://api-sandbox.circle.com/v1/paymentIntents' \
--header 'X-Request-Id: ${GUID}' \
--header 'Authorization: Bearer ${YOUR_API_KEY}' \
--header 'Content-Type: application/json' \
--data-raw '{
  "idempotencyKey": "17607606-e383-4874-87c3-7e46a5dc03dd",
  "currency": "USD",
  "settlementCurrency": "USD",
  "paymentMethods": [
    {
      "type": "blockchain",
      "chain": "ETH"
    }
  ]
}'

/**
 * See installation instructions at
 * https://developers.circle.com/circle-mint/circle-sdks
 */
import {
  Circle,
  CircleEnvironments,
  PaymentIntentCreationRequest,
} from "@circle-fin/circle-sdk";
import crypto from "crypto";

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

async function createContinuousPaymentIntent(): Promise<void> {
  const reqBody: PaymentIntentCreationRequest = {
    currency: "USD",
    settlementCurrency: "USD",
    paymentMethods: [
      {
        type: "blockchain",
        chain: "ETH",
      },
    ],
    idempotencyKey: crypto.randomUUID(),
  };
  const resp = await circle.cryptoPaymentIntents.createPaymentIntent(reqBody);
  console.log(resp.data);
}

void createContinuousPaymentIntent();

Response

{
  "data": {
    "type": "continuous",
    "id": "e7b49cb6-1f78-4a0f-8fd6-35fc74dca335",
    "amountPaid": {
      "amount": "0.00",
      "currency": "USD"
    },
    "amountRefunded": {
      "amount": "0.00",
      "currency": "USD"
    },
    "settlementCurrency": "USD",
    "paymentMethods": [
      {
        "type": "blockchain",
        "chain": "ETH"
      }
    ],
    "timeline": [
      {
        "status": "created",
        "time": "2026-03-23T17:41:19.986668Z"
      }
    ],
    "createDate": "2026-03-23T17:41:19.979669Z",
    "updateDate": "2026-03-23T17:41:19.979669Z",
    "merchantWalletId": "1000700366",
    "currency": "USD"
  }
}

Create a payment intent

purposeOfTransfer is required. Use a payment reason code other than PMT006. Use customerExternalRef to pass an optional reference string for the customer.Create a payment intent:

curl --location --request POST 'https://api-sandbox.circle.com/v1/paymentIntents' \
--header 'X-Request-Id: ${GUID}' \
--header 'Authorization: Bearer ${YOUR_API_KEY}' \
--header 'Content-Type: application/json' \
--data-raw '{
  "idempotencyKey": "17607606-e383-4874-87c3-7e46a5dc03dd",
  "currency": "USD",
  "settlementCurrency": "USD",
  "purposeOfTransfer": "PMT001",
  "paymentMethods": [
    {
      "type": "blockchain",
      "chain": "ETH"
    }
  ],
  "metadata": {
    "customerExternalRef": "310c458a-18eb-4640-8a9a-586d9448ae69"
  }
}'

/**
 * See installation instructions at
 * https://developers.circle.com/circle-mint/circle-sdks
 */
import {
  Circle,
  CircleEnvironments,
  PaymentIntentCreationRequest,
} from "@circle-fin/circle-sdk";
import crypto from "crypto";

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

async function createContinuousPaymentIntent(): Promise<void> {
  const reqBody: PaymentIntentCreationRequest = {
    currency: "USD",
    settlementCurrency: "USD",
    purposeOfTransfer: "PMT001",
    paymentMethods: [
      {
        type: "blockchain",
        chain: "ETH",
      },
    ],
    metadata: {
      customerExternalRef: "310c458a-18eb-4640-8a9a-586d9448ae69",
    },
    idempotencyKey: crypto.randomUUID(),
  };
  const resp = await circle.cryptoPaymentIntents.createPaymentIntent(reqBody);
  console.log(resp.data);
}

void createContinuousPaymentIntent();

Response

{
  "data": {
    "type": "continuous",
    "id": "e7b49cb6-1f78-4a0f-8fd6-35fc74dca335",
    "amountPaid": {
      "amount": "0.00",
      "currency": "USD"
    },
    "amountRefunded": {
      "amount": "0.00",
      "currency": "USD"
    },
    "settlementCurrency": "USD",
    "paymentMethods": [
      {
        "type": "blockchain",
        "chain": "ETH"
      }
    ],
    "timeline": [
      {
        "status": "created",
        "time": "2026-03-23T17:41:19.986668Z"
      }
    ],
    "createDate": "2026-03-23T17:41:19.979669Z",
    "updateDate": "2026-03-23T17:41:19.979669Z",
    "merchantWalletId": "1000700366",
    "currency": "USD",
    "purposeOfTransfer": "PMT001",
    "customerExternalRef": "310c458a-18eb-4640-8a9a-586d9448ae69"
  }
}

Webhook notification

{
  "clientId": "5b057f1e-743c-4aeb-beeb-ef7b2e16f291",
  "notificationType": "paymentIntents",
  "version": 1,
  "customAttributes": {
    "clientId": "5b057f1e-743c-4aeb-beeb-ef7b2e16f291"
  },
  "paymentIntent": {
    "type": "continuous",
    "id": "e7b49cb6-1f78-4a0f-8fd6-35fc74dca335",
    "amountPaid": {
      "amount": "0.00",
      "currency": "USD"
    },
    "amountRefunded": {
      "amount": "0.00",
      "currency": "USD"
    },
    "settlementCurrency": "USD",
    "paymentMethods": [
      {
        "type": "blockchain",
        "chain": "ETH"
      }
    ],
    "timeline": [
      {
        "status": "created",
        "time": "2026-03-23T17:41:19.986668Z"
      }
    ],
    "createDate": "2026-03-23T17:41:19.979669Z",
    "updateDate": "2026-03-23T17:41:19.979669Z",
    "merchantWalletId": "12345",
    "currency": "USD"
  }
}

2. Acquire blockchain address customer will pay to

For security reasons, the API does not return the deposit blockchain address in the create response. To retrieve the blockchain deposit address, you have two options:

Subscribe to webhook notifications
Poll Circle APIs

Option 1: Webhook notification

To receive webhook notifications, follow the steps in Set up a webhook endpoint. After you subscribe, you receive updates when the payment intent changes. When paymentMethods.address is set, a notification arrives with a new timeline entry and status: active.

Payment intent webhook notification

{
  "clientId": "5b057f1e-743c-4aeb-beeb-ef7b2e16f291",
  "notificationType": "paymentIntents",
  "version": 1,
  "customAttributes": {
    "clientId": "5b057f1e-743c-4aeb-beeb-ef7b2e16f291"
  },
  "paymentIntent": {
    "type": "continuous",
    "id": "e7b49cb6-1f78-4a0f-8fd6-35fc74dca335",
    "amountPaid": {
      "amount": "0.00",
      "currency": "USD"
    },
    "amountRefunded": {
      "amount": "0.00",
      "currency": "USD"
    },
    "settlementCurrency": "USD",
    "paymentMethods": [
      {
        "type": "blockchain",
        "chain": "ETH",
        "address": "0xfd5a9f666d96022d13a73e3638fb7ec958696fbe"
      }
    ],
    "fees": [
      {
        "type": "blockchainLeaseFee",
        "amount": "0.00",
        "currency": "USD"
      }
    ],
    "timeline": [
      {
        "status": "active",
        "time": "2026-03-23T17:41:23.450386Z"
      },
      {
        "status": "created",
        "time": "2026-03-23T17:41:19.986668Z"
      }
    ],
    "createDate": "2026-03-23T17:41:19.979669Z",
    "updateDate": "2026-03-23T17:41:23.405690Z",
    "merchantWalletId": "12345",
    "currency": "USD"
  }
}

Option 2: Poll payment intent endpoint

If you prefer to poll get a payment intent, send GET requests until you receive paymentMethods.address. Retrieve payment intent:

curl --location --request GET 'https://api-sandbox.circle.com/v1/paymentIntents/{id}' \
--header 'X-Request-Id: ${GUID}' \
--header 'Authorization: Bearer ${YOUR_API_KEY}'

/**
 * See installation instructions at
 * https://developers.circle.com/circle-mint/circle-sdks
 */
import { Circle, CircleEnvironments } from "@circle-fin/circle-sdk";

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

function delay(time: number): Promise<void> {
  return new Promise((resolve) => {
    setTimeout(resolve, time);
  });
}

async function getPaymentIntent(paymentIntentId: string) {
  const resp =
    await circle.cryptoPaymentIntents.getPaymentIntent(paymentIntentId);
  return resp.data;
}

async function pollPaymentIntent(): Promise<void> {
  const paymentIntentId = "payment-intent-id";
  const pollInterval = 500; // Interval (in ms) by which to poll

  let resp: Awaited<ReturnType<typeof getPaymentIntent>>;
  while (true) {
    resp = await getPaymentIntent(paymentIntentId);
    const depositAddress = resp.data?.paymentMethods[0]?.address;
    if (depositAddress) break;
    await delay(pollInterval);
  }
  console.log(resp);
}

void pollPaymentIntent();

Response

{
  "data": {
    "type": "continuous",
    "id": "e7b49cb6-1f78-4a0f-8fd6-35fc74dca335",
    "amountPaid": {
      "amount": "0.00",
      "currency": "USD"
    },
    "amountRefunded": {
      "amount": "0.00",
      "currency": "USD"
    },
    "settlementCurrency": "USD",
    "paymentMethods": [
      {
        "type": "blockchain",
        "chain": "ETH",
        "address": "0xfd5a9f666d96022d13a73e3638fb7ec958696fbe"
      }
    ],
    "fees": [
      {
        "type": "blockchainLeaseFee",
        "amount": "0.00",
        "currency": "USD"
      }
    ],
    "timeline": [
      {
        "status": "active",
        "time": "2026-03-23T17:41:23.450386Z"
      },
      {
        "status": "created",
        "time": "2026-03-23T17:41:19.986668Z"
      }
    ],
    "createDate": "2026-03-23T17:41:19.979669Z",
    "updateDate": "2026-03-23T17:41:23.405690Z",
    "merchantWalletId": "12345",
    "currency": "USD"
  }
}

3. Enable customer payment

Share paymentMethods.address with the customer so they can send funds on the correct chain.

A continuous payment intent doesn’t define a fixed amount on create; you communicate any specific charge (for example an invoice total) from your own checkout or UI.

You can present the address two ways:

as plain text the customer can cut and paste; or
as a QR code the customer can scan using an app.

The customer then sends payment from their wallet (custodial or non-custodial).

For transient payment intents, set expiresOn to limit the payment window. The value must be no more than 24 hours after creation, or the API returns error 1128.

4. Receive payment from Circle

Once Circle detects the onchain payment, it creates a Payment resource linked to the original Payment Intent and updates its status. Your firm then receives payment through the method specified.

Option 1: Webhook notifications

Payment intent webhook notification

{
  "clientId": "5b057f1e-743c-4aeb-beeb-ef7b2e16f291",
  "notificationType": "paymentIntents",
  "version": 1,
  "customAttributes": {
    "clientId": "5b057f1e-743c-4aeb-beeb-ef7b2e16f291"
  },
  "paymentIntent": {
    "type": "continuous",
    "id": "e7b49cb6-1f78-4a0f-8fd6-35fc74dca335",
    "amountPaid": {
      "amount": "5.00",
      "currency": "USD"
    },
    "amountRefunded": {
      "amount": "0.00",
      "currency": "USD"
    },
    "settlementCurrency": "USD",
    "paymentMethods": [
      {
        "type": "blockchain",
        "chain": "ETH",
        "address": "0xfd5a9f666d96022d13a73e3638fb7ec958696fbe"
      }
    ],
    "fees": [
      {
        "type": "blockchainLeaseFee",
        "amount": "0.00",
        "currency": "USD"
      },
      {
        "type": "totalPaymentFees",
        "amount": "0.00",
        "currency": "USD"
      }
    ],
    "timeline": [
      {
        "status": "active",
        "time": "2026-03-23T17:41:23.450386Z"
      },
      {
        "status": "created",
        "time": "2026-03-23T17:41:19.986668Z"
      }
    ],
    "createDate": "2026-03-23T17:41:19.979669Z",
    "updateDate": "2026-03-23T17:52:18.080633Z",
    "merchantWalletId": "12345",
    "currency": "USD"
  }
}

Payment webhook notification

{
  "clientId": "5b057f1e-743c-4aeb-beeb-ef7b2e16f291",
  "notificationType": "payments",
  "version": 1,
  "customAttributes": {
    "clientId": "5b057f1e-743c-4aeb-beeb-ef7b2e16f291"
  },
  "payment": {
    "id": "021ff661-e7d5-332f-bb9c-e43870608f26",
    "type": "payment",
    "status": "pending",
    "amount": {
      "amount": "5.00",
      "currency": "USD"
    },
    "createDate": "2026-03-23T17:49:54.197Z",
    "updateDate": "2026-03-23T17:49:54.259Z",
    "merchantId": "5b057f1e-743c-4aeb-beeb-ef7b2e16f291",
    "merchantWalletId": "12345",
    "paymentIntentId": "e7b49cb6-1f78-4a0f-8fd6-35fc74dca335",
    "fromAddresses": {
      "chain": "ETH",
      "addresses": ["0x6dbe810e3314546009bd6e1b29f9031211cda5d2"]
    },
    "depositAddress": {
      "chain": "ETH",
      "address": "0xfd5a9f666d96022d13a73e3638fb7ec958696fbe"
    },
    "transactionHash": "0xfbc0f1c8256af3453fd3be7a1491e3581e072022a29ffc78cf129a662182305e"
  }
}

For Circle Singapore (CIRCLE_SG) merchants, a Payment in status: "pending" may include a statusReason field indicating a compliance hold. For example, compliance_review means Circle is awaiting Personally Identifiable Information (PII) before releasing funds. For the full list of values, see Stablecoin payin states.

Option 2: Retrieve payment intent and payment

Retrieve a payment intent:

curl --location --request GET 'https://api-sandbox.circle.com/v1/paymentIntents/{id}' \
--header 'X-Request-Id: ${GUID}' \
--header 'Authorization: Bearer ${YOUR_API_KEY}'

/**
 * See installation instructions at
 * https://developers.circle.com/circle-mint/circle-sdks
 */
import { Circle, CircleEnvironments } from "@circle-fin/circle-sdk";

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

async function getPaymentIntent(): Promise<void> {
  const paymentIntentId = "<payment-intent-id>";
  const resp =
    await circle.cryptoPaymentIntents.getPaymentIntent(paymentIntentId);

  console.log(resp.data);
}

void getPaymentIntent();

Response

{
  "data": {
    "type": "continuous",
    "id": "e7b49cb6-1f78-4a0f-8fd6-35fc74dca335",
    "amountPaid": {
      "amount": "5.00",
      "currency": "USD"
    },
    "amountRefunded": {
      "amount": "0.00",
      "currency": "USD"
    },
    "settlementCurrency": "USD",
    "paymentMethods": [
      {
        "type": "blockchain",
        "chain": "ETH",
        "address": "0xfd5a9f666d96022d13a73e3638fb7ec958696fbe"
      }
    ],
    "fees": [
      {
        "type": "blockchainLeaseFee",
        "amount": "0.00",
        "currency": "USD"
      },
      {
        "type": "totalPaymentFees",
        "amount": "0.00",
        "currency": "USD"
      }
    ],
    "timeline": [
      {
        "status": "active",
        "time": "2026-03-23T17:41:23.450386Z"
      },
      {
        "status": "created",
        "time": "2026-03-23T17:41:19.986668Z"
      }
    ],
    "createDate": "2026-03-23T17:41:19.979669Z",
    "updateDate": "2026-03-23T17:52:18.080633Z",
    "merchantWalletId": "12345",
    "currency": "USD"
  }
}

Retrieve a payment:

curl --location --request GET 'https://api-sandbox.circle.com/v1/payments/{id}' \
--header 'X-Request-Id: ${GUID}' \
--header 'Authorization: Bearer ${YOUR_API_KEY}'

/**
 * See installation instructions at
 * https://developers.circle.com/circle-mint/circle-sdks
 */
import { Circle, CircleEnvironments } from "@circle-fin/circle-sdk";

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

async function getPayment(): Promise<void> {
  const paymentId = "<payment-id>";
  const resp = await circle.payments.getPayment(paymentId);

  console.log(resp.data);
}

void getPayment();

Response

{
  "data": {
    "id": "021ff661-e7d5-332f-bb9c-e43870608f26",
    "type": "payment",
    "status": "paid",
    "amount": {
      "amount": "5.00",
      "currency": "USD"
    },
    "fees": {
      "amount": "0.00",
      "currency": "USD"
    },
    "createDate": "2026-03-23T17:49:54.197184Z",
    "updateDate": "2026-03-23T17:52:17.910610Z",
    "merchantId": "5b057f1e-743c-4aeb-beeb-ef7b2e16f291",
    "merchantWalletId": "12345",
    "paymentIntentId": "e7b49cb6-1f78-4a0f-8fd6-35fc74dca335",
    "settlementAmount": {
      "amount": "5.00",
      "currency": "USD"
    },
    "fromAddresses": {
      "chain": "ETH",
      "addresses": ["0x6dbe810e3314546009bd6e1b29f9031211cda5d2"]
    },
    "depositAddress": {
      "chain": "ETH",
      "address": "0xfd5a9f666d96022d13a73e3638fb7ec958696fbe"
    },
    "transactionHash": "0xfbc0f1c8256af3453fd3be7a1491e3581e072022a29ffc78cf129a662182305e"
  }
}

For blockchains that require a ‘memo’ or ‘address tag’ (XLM, HBAR, etc.), the optional addressTag field will be present in the depositAddress object.

Fiat payouts

Managed Payments

Stablecoin payments

Quickstart: Receive stablecoin payins

Prerequisites

Sequence diagram

Steps

1. Pay with stablecoin

Create a payment intent

2. Acquire blockchain address customer will pay to

Option 1: Webhook notification

Option 2: Poll payment intent endpoint

3. Enable customer payment

4. Receive payment from Circle

Option 1: Webhook notifications

Option 2: Retrieve payment intent and payment

​Prerequisites

​Sequence diagram

​Steps

​1. Pay with stablecoin

​Create a payment intent

​2. Acquire blockchain address customer will pay to

​Option 1: Webhook notification

​Option 2: Poll payment intent endpoint

​3. Enable customer payment

​4. Receive payment from Circle

​Option 1: Webhook notifications

​Option 2: Retrieve payment intent and payment

Prerequisites

Sequence diagram

Steps

1. Pay with stablecoin

Create a payment intent

2. Acquire blockchain address customer will pay to

Option 1: Webhook notification

Option 2: Poll payment intent endpoint

3. Enable customer payment

4. Receive payment from Circle

Option 1: Webhook notifications

Option 2: Retrieve payment intent and payment