Quickstart: Receive a Stablecoin Payin

Use the Crypto Deposits API to accept onchain USDC or EURC stablecoin payins into Circle Mint from your customers’ wallets. You create the payment intent, share the deposit address, have the customer send funds, then confirm the transfer using the API or webhooks. The examples in this quickstart use Ethereum, but you can use any supported blockchain.

Prerequisites

Before you begin this tutorial, ensure you’ve:

Obtained a Circle Mint sandbox API key with access to the Crypto Deposits API (stablecoin payins).
Obtained a merchantWalletId for the wallet that receives settled funds.
Installed cURL for API calls.
(Optional) Configured webhook notifications.

Step 1: Create a payment intent

Call Create a payment intent when the customer chooses to pay with USDC or EURC onchain. Choose continuous or transient mode. Expected result: a response with a payment intent id and timeline including created.

Continuous (default mode)
Transient

Continuous payment intents are the default type. You do not include an amount at creation.Example request:

cURL

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",
  "merchantWalletId": "${MERCHANT_WALLET_ID}",
  "paymentMethods": [
    {
      "type": "blockchain",
      "chain": "ETH"
    }
  ],
  "type": "continuous"
}'

Example response:

JSON

{
  "data": {
    "id": "e2e90ba3-9d1f-490d-9460-24ac6eb55a1b",
    "currency": "USD",
    "settlementCurrency": "USD",
    "amountPaid": {
      "amount": "0.00",
      "currency": "USD"
    },
    "paymentMethods": [
      {
        "type": "blockchain",
        "chain": "ETH"
      }
    ],
    "timeline": [
      {
        "status": "created",
        "time": "2023-01-21T20:13:35.579331Z"
      }
    ],
    "type": "continuous",
    "createDate": "2023-01-21T20:13:35.578678Z",
    "updateDate": "2023-01-21T20:13:35.578678Z"
  }
}

Transient intents include a specific amount and are intended for a single checkout payment. You must set the type to transient.Example request:

cURL

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",
  "type": "transient",
  "amount": {
    "amount": "1.00",
    "currency": "USD"
  },
  "settlementCurrency": "USD",
  "merchantWalletId": "${MERCHANT_WALLET_ID}",
  "paymentMethods": [
    {
      "type": "blockchain",
      "chain": "ETH"
    }
  ]
}'

Example response:

JSON

{
  "data": {
    "id": "6e4d4047-db14-4c09-b238-1215aee50d03",
    "amount": {
      "amount": "1.00",
      "currency": "USD"
    },
    "amountPaid": {
      "amount": "0.00",
      "currency": "USD"
    },
    "amountRefunded": {
      "amount": "0.00",
      "currency": "USD"
    },
    "settlementCurrency": "USD",
    "paymentMethods": [
      {
        "type": "blockchain",
        "chain": "ETH"
      }
    ],
    "paymentIds": [],
    "timeline": [
      {
        "status": "created",
        "time": "2022-07-21T20:13:35.579331Z"
      }
    ],
    "createDate": "2022-07-21T20:13:35.578678Z",
    "updateDate": "2022-07-21T20:19:24.859052Z"
  }
}

Step 2: Obtain the deposit address

Circle does not return the deposit address in the create response. Use webhooks or poll Get a payment intent until paymentMethods.address is set. Expected result: you have the onchain deposit address to show the customer.

Webhooks
Polling

After you subscribe to notifications for paymentIntents, you receive updates when the payment intent changes. When paymentMethods.address is set, the payload includes an updated timeline of the historical payment intent statuses and timestamps.Expected result: the notification includes paymentIntent.paymentMethods with address and timeline with pending after the address is assigned.Example paymentIntents notification after the deposit address is assigned:

{
  "clientId": "f1397191-56e6-42fd-be86-0a7b9bd91522",
  "notificationType": "paymentIntents",
  "version": 1,
  "customAttributes": { "clientId": "f1397191-56e6-42fd-be86-0a7b9bd91522" },
  "paymentIntent": {
    "id": "e2e90ba3-9d1f-490d-9460-24ac6eb55a1b",
    "currency": "USD",
    "settlementCurrency": "USD",
    "amountPaid": { "amount": "0.00", "currency": "USD" },
    "amountRefunded": { "amount": "0.00", "currency": "USD" },
    "paymentMethods": [
      {
        "type": "blockchain",
        "chain": "ETH",
        "address": "0x97de855690955e0da79ce5c1b6804847e7070c7f"
      }
    ],
    "fees": [
      { "type": "blockchainLeaseFee", "amount": "0.00", "currency": "USD" }
    ],
    "paymentIds": [],
    "refundIds": [],
    "timeline": [
      { "status": "pending", "time": "2023-01-21T20:13:38.188286Z" },
      { "status": "created", "time": "2023-01-21T20:13:35.579331Z" }
    ],
    "type": "continuous",
    "createDate": "2023-01-21T20:13:35.578678Z",
    "updateDate": "2023-01-21T20:13:38.186831Z"
  }
}

Call the Get a payment intent endpoint until paymentMethods.address is present in the response.Expected result: the response data includes paymentMethods with address for the deposit.Example request:

cURL

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

Example response after the address is available:

{
  "data": {
    "id": "e2e90ba3-9d1f-490d-9460-24ac6eb55a1b",
    "currency": "USD",
    "settlementCurrency": "USD",
    "amountPaid": { "amount": "0.00", "currency": "USD" },
    "amountRefunded": { "amount": "0.00", "currency": "USD" },
    "paymentMethods": [
      {
        "type": "blockchain",
        "chain": "ETH",
        "address": "0x97de855690955e0da79ce5c1b6804847e7070c7f"
      }
    ],
    "fees": [
      { "type": "blockchainLeaseFee", "amount": "0.00", "currency": "USD" }
    ],
    "paymentIds": [],
    "refundIds": [],
    "timeline": [
      { "status": "pending", "time": "2023-01-21T20:13:38.188286Z" },
      { "status": "created", "time": "2023-01-21T20:13:35.579331Z" }
    ],
    "type": "continuous",
    "createDate": "2023-01-21T20:13:35.578678Z",
    "updateDate": "2023-01-21T20:13:38.186831Z"
  }
}

Step 3: Have the customer pay onchain

Display the deposit address and have the customer send USDC or EURC on the chosen chain. Expected result: an onchain transfer to the deposit address is submitted (you confirm settlement in Step 4).

3.1. Display the deposit address

Give the customer the deposit address, the stablecoin to send (USDC or EURC), and for transient intents the amount. Plain text or a QR code is fine. Expected result: the customer can send funds from their wallet.

For transient payment intents, you can display the expiresOn time to show the customer how long they have to pay.If the customer does not send funds before expiresOn, the payment intent moves to a complete status with context expired. You cannot reuse an expired intent. Create a new payment intent to retry the checkout.

3.2. Customer sends funds onchain

The customer sends USDC or EURC to the deposit address on the specified blockchain. Expected result: the transfer appears onchain against that address.

Step 4: Confirm payment completion

After Circle confirms the transfer, it updates the payment intent and creates a payment record for that inbound transfer. Confirm the intent and the payment match what you expect using webhooks or polling. Expected result: payment intent timeline shows complete with context paid, and the linked payment has status paid.

4.1. Inspect the payment intent

Webhooks
Polling

Subscribe to paymentIntents notifications. After the customer pays, the payload includes an updated timeline, amountPaid, and paymentIds.Expected result: paymentIntent in the notification includes:

timeline with complete and context paid
paymentIds listing the payin payment for this transfer
amountPaid reflecting the settled amount

Example when the payment intent is complete and paid:

{
  "clientId": "f1397191-56e6-42fd-be86-0a7b9bd91522",
  "notificationType": "paymentIntents",
  "version": 1,
  "customAttributes": { "clientId": "f1397191-56e6-42fd-be86-0a7b9bd91522" },
  "paymentIntent": {
    "id": "e2e90ba3-9d1f-490d-9460-24ac6eb55a1b",
    "currency": "USD",
    "settlementCurrency": "USD",
    "amountPaid": { "amount": "1.00", "currency": "USD" },
    "amountRefunded": { "amount": "0.00", "currency": "USD" },
    "paymentMethods": [
      {
        "type": "blockchain",
        "chain": "ETH",
        "address": "0x97de855690955e0da79ce5c1b6804847e7070c7f"
      }
    ],
    "fees": [
      { "type": "blockchainLeaseFee", "amount": "0.00", "currency": "USD" },
      { "type": "totalPaymentFees", "amount": "0.01", "currency": "USD" }
    ],
    "paymentIds": ["66c56b6a-fc79-338b-8b94-aacc4f0f18de"],
    "refundIds": [],
    "timeline": [
      {
        "status": "complete",
        "context": "paid",
        "time": "2023-01-21T20:19:24.861094Z"
      },
      { "status": "pending", "time": "2023-01-21T20:13:38.188286Z" },
      { "status": "created", "time": "2023-01-21T20:13:35.579331Z" }
    ],
    "type": "continuous",
    "createDate": "2023-01-21T20:13:35.578678Z",
    "updateDate": "2023-01-21T20:19:24.859052Z"
  }
}

Call the Get a payment intent endpoint on an interval until the newest timeline entry has status as complete and context as paid, or until amountPaid matches what you expect.Expected result: the response data includes:

timeline with complete and context paid
paymentIds listing the payin payment for this transfer
amountPaid reflecting the settled amount

Example request:

curl --location --request GET 'https://api-sandbox.circle.com/v1/paymentIntents/e2e90ba3-9d1f-490d-9460-24ac6eb55a1b' \
--header 'X-Request-Id: ${GUID}' \
--header 'Authorization: Bearer ${YOUR_API_KEY}'

Example response when one payin has completed:

{
  "data": {
    "id": "e2e90ba3-9d1f-490d-9460-24ac6eb55a1b",
    "currency": "USD",
    "settlementCurrency": "USD",
    "amountPaid": { "amount": "1.00", "currency": "USD" },
    "amountRefunded": { "amount": "0.00", "currency": "USD" },
    "paymentMethods": [
      {
        "type": "blockchain",
        "chain": "ETH",
        "address": "0x97de855690955e0da79ce5c1b6804847e7070c7f"
      }
    ],
    "fees": [
      { "type": "blockchainLeaseFee", "amount": "0.00", "currency": "USD" },
      { "type": "totalPaymentFees", "amount": "0.01", "currency": "USD" }
    ],
    "paymentIds": ["66c56b6a-fc79-338b-8b94-aacc4f0f18de"],
    "refundIds": [],
    "timeline": [
      {
        "status": "complete",
        "context": "paid",
        "time": "2023-01-21T20:19:24.861094Z"
      },
      { "status": "pending", "time": "2023-01-21T20:13:38.188286Z" },
      { "status": "created", "time": "2023-01-21T20:13:35.579331Z" }
    ],
    "type": "continuous",
    "createDate": "2023-01-21T20:13:35.578678Z",
    "updateDate": "2023-01-21T20:19:24.859052Z"
  }
}

For continuous payment intents, the same deposit address can receive multiple transfers. Each settled transfer adds another ID to paymentIds.

4.2. Inspect the payment for the same transfer

The payment record holds the onchain transactionHash and the customer’s fromAddresses for that transfer.

Webhooks
Polling

Subscribe to payments notifications to receive the updated payment object when the transfer settles.Expected result: payment in the notification has status paid, a populated transactionHash, and fromAddresses for the sender.

JSON

{
  "clientId": "f1397191-56e6-42fd-be86-0a7b9bd91522",
  "notificationType": "payments",
  "version": 1,
  "customAttributes": { "clientId": "f1397191-56e6-42fd-be86-0a7b9bd91522" },
  "payment": {
    "id": "66c56b6a-fc79-338b-8b94-aacc4f0f18de",
    "type": "payment",
    "status": "paid",
    "amount": { "amount": "1.00", "currency": "USD" },
    "fees": { "amount": "0.01", "currency": "USD" },
    "createDate": "2023-01-21T20:16:35.092Z",
    "updateDate": "2023-01-21T20:19:24.719Z",
    "merchantId": "f1397191-56e6-42fd-be86-0a7b9bd91522",
    "merchantWalletId": "1000999922",
    "paymentIntentId": "e2e90ba3-9d1f-490d-9460-24ac6eb55a1b",
    "settlementAmount": { "amount": "1.00", "currency": "USD" },
    "fromAddresses": {
      "chain": "ETH",
      "addresses": ["0x0d4344cff68f72a5b9abded37ca5862941a62050"]
    },
    "depositAddress": {
      "chain": "ETH",
      "address": "0x97de855690955e0da79ce5c1b6804847e7070c7f"
    },
    "transactionHash": "0x7351585460bd657f320b9afa02a52c26d89272d0d10cc29913eb8b28e64fd906"
  }
}

Poll the Get a payment endpoint using the ID from paymentIds on the payment intent. Stop when that payment status is paid and, if you check onchain, when transactionHash matches the transfer you expect.For continuous payment intents, paymentIds can list more than one transfer over time. Make sure you poll the ID for this specific transfer.Expected result: data has type payment and status paid, a populated transactionHash, and fromAddresses for the sender when the payin has settled.Example request:

cURL

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

Example response:

JSON

{
  "data": {
    "id": "66c56b6a-fc79-338b-8b94-aacc4f0f18de",
    "type": "payment",
    "status": "paid",
    "amount": { "amount": "1.00", "currency": "USD" },
    "fees": { "amount": "0.01", "currency": "USD" },
    "createDate": "2023-01-21T20:16:35.092Z",
    "updateDate": "2023-01-21T20:19:24.719Z",
    "merchantId": "f1397191-56e6-42fd-be86-0a7b9bd91522",
    "merchantWalletId": "1000999922",
    "paymentIntentId": "e2e90ba3-9d1f-490d-9460-24ac6eb55a1b",
    "settlementAmount": { "amount": "1.00", "currency": "USD" },
    "fromAddresses": {
      "chain": "ETH",
      "addresses": ["0x0d4344cff68f72a5b9abded37ca5862941a62050"]
    },
    "depositAddress": {
      "chain": "ETH",
      "address": "0x97de855690955e0da79ce5c1b6804847e7070c7f"
    },
    "transactionHash": "0x7351585460bd657f320b9afa02a52c26d89272d0d10cc29913eb8b28e64fd906"
  }
}

For blockchains that use a memo or address tag (for example, XLM or HBAR), the addressTag field can appear on depositAddress in payment payloads.

The payment is complete when status is paid.

Mint

StableFX

​Prerequisites

​Step 1: Create a payment intent

​Step 2: Obtain the deposit address

​Step 3: Have the customer pay onchain

​3.1. Display the deposit address

​3.2. Customer sends funds onchain

​Step 4: Confirm payment completion

​4.1. Inspect the payment intent

​4.2. Inspect the payment for the same transfer

Prerequisites

Step 1: Create a payment intent

Step 2: Obtain the deposit address

Step 3: Have the customer pay onchain

3.1. Display the deposit address

3.2. Customer sends funds onchain

Step 4: Confirm payment completion

4.1. Inspect the payment intent

4.2. Inspect the payment for the same transfer