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 confirm the payment after Circle links the onchain transfer to your intent. The steps use a continuous payment intent, the default pattern for a stable receive address per account. For how payment intents and payments progress, see Stablecoin payin and payout lifecycle.

To accept a one-time payment with a fixed amount and expiry window, use a transient payment intent instead. See How-to: Receive a stablecoin payin.

Prerequisites

Before you begin, ensure that you’ve:

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.
(Optional) Set up a webhook endpoint to receive payment intent and payment events. See Set up a webhook endpoint.
(Optional) Funded a payer wallet with USDC and native gas on the blockchain you set on the intent, for an end-to-end test. For example, use Sepolia ETH when the intent uses an Ethereum test blockchain.

Step 1: Create a payment intent

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();

The response returns a continuous intent with a created status and no deposit address yet:

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 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();

The response returns a continuous intent with a created status and no deposit address yet:

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

If you subscribed to webhooks, you also receive a paymentIntents notification for the new 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"
      }
    ],
    "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"
  }
}

Step 2: Get the deposit address

For security reasons, the API doesn’t return the deposit address in the create response. Retrieve it from a webhook notification or by polling the payment intent.

Webhook
Polling

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

To poll get a payment intent, send GET requests until the response includes paymentMethods.address:

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();

When the address is ready, the intent status is active and the response includes paymentMethods.address:

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

Show paymentMethods.address to the customer so they can send USDC on the correct blockchain. Present it as plain text the customer can copy, or as a QR code they can scan with a wallet app.

A continuous payment intent doesn’t define a fixed amount on create. You communicate any specific charge, such as an invoice total, from your own checkout or UI.

The customer sends the payment from their custodial or non-custodial wallet to the deposit address.

Step 4: Confirm the payment

When Circle detects the onchain transfer, it creates a payment linked to the intent and updates the intent’s amountPaid. The payment starts as pending and moves to paid when the funds settle. Track it with webhooks or by polling.

Webhook
Polling

Circle sends a paymentIntents notification with the updated amountPaid:

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

Circle also sends a payments notification when it detects the transfer, with status set to pending. A second payments notification arrives when the payment settles and status changes to paid:

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.

Retrieve the payment intent to check amountPaid:

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

Then retrieve the payment by its ID:

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();

The payment is complete when status is paid:

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

Step 1: Create a payment intent

Step 2: Get the deposit address

Step 4: Confirm the payment

​Prerequisites

​Step 1: Create a payment intent

​Step 2: Get the deposit address

​Step 3: Share the deposit address with the customer

​Step 4: Confirm the payment

Prerequisites

Step 1: Create a payment intent

Step 2: Get the deposit address

Step 3: Share the deposit address with the customer

Step 4: Confirm the payment