Crypto Payments Quickstart

This quickstart will step through accepting crypto payments in USDC on the Ethereum Chain as an example. With exception to replacing a few values, these steps should also be followed when using different currencies and chains.

Steps:

  1. Set up payment intent to pay with Crypto
  2. Acquire blockchain address customer will pay to
  3. Customer pays
  4. Receive payment
45584558

1. Pay with Crypto

Once the customer reaches checkout and confirms they would like to pay with USDC on Ethereum, send a request to create a payment intent. Within this payment intent request you will specify the amount, currency, settlement currency, and chain.

curl --location --request POST 'https://api-sandbox.circle.com/v1/paymentIntents' \
--header 'X-Requested-Id: ${GUID}' \
--header 'Authorization: Bearer ${YOUR_API_KEY}' \
--header 'Content-Type: application/json' \
--data-raw '{
 "idempotencyKey": "17607606-e383-4874-87c3-7e46a5dc03dd",
 "amount": {
   "amount": "1.00",
   "currency": "USD"
 },
 "settlementCurrency": "USD"a,
 "paymentMethods": [
   {
     "type": "blockchain",
     "chain": "ETH"
   }
 ]
}'
{
 "data": {
   "id": "6e4d4047-db14-4c09-b238-1215aee50d03",
   "amount": {
     "amount": "1.00",
     "currency": "USD"
   },
   "amountPaid": {
     "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",
 }
}

📘

We do not synchronously return the deposit blockchain address.

{
 "clientId": "f1397191-56e6-42fd-be86-0a7b9bd91522",
 "notificationType": "paymentIntents",
 "version": 1,
 "customAttributes": { "clientId": "f1397191-56e6-42fd-be86-0a7b9bd91522" },
 "paymentIntent": {
   "id": "6e4d4047-db14-4c09-b238-1215aee50d03",
   "amount": { "amount": "1.00", "currency": "USD" },
   "amountPaid": { "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:13:35.578678Z"
 }
}

2. Blockchain Deposit Address

To retrieve the blockchain deposit address, you have two options:

  1. Subscribe to webhook notifications
  2. Poll Circle APIs

Option 1: Webhook Notification

To get up and running with the webhook notifications, please head over to the notification quickstart. Once you have subscribed to the notifications, you will receive updates for the payment intent whenever the resource has been updated. In this case, when the paymentMethods.address has been set, a notification will be sent with a new timeline object possessing a status of pending.

{
 "clientId": "f1397191-56e6-42fd-be86-0a7b9bd91522",
 "notificationType": "paymentIntents",
 "version": 1,
 "customAttributes": { "clientId": "f1397191-56e6-42fd-be86-0a7b9bd91522" },
 "paymentIntent": {
   "id": "6e4d4047-db14-4c09-b238-1215aee50d03",
   "amount": { "amount": "1.00", "currency": "USD" },
   "amountPaid": { "amount": "0.00", "currency": "USD" },
   "settlementCurrency": "USD",
   "paymentMethods": [
     {
       "type": "blockchain",
       "chain": "ETH",
       "address": "0x97de855690955e0da79ce5c1b6804847e7070c7f"
     }
   ],
   "fees": [
     { "type": "blockchainLeaseFee", "amount": "0.00", "currency": "USD" }
   ],
   "paymentIds": [],
   "timeline": [
     { "status": "pending", "time": "2022-07-21T20:13:38.188286Z" },
     { "status": "created", "time": "2022-07-21T20:13:35.579331Z" }
   ],
   "createDate": "2022-07-21T20:13:35.578678Z",
   "updateDate": "2022-07-21T20:13:38.186831Z",
   "expiresOn": "2022-07-21T21:13:38.087275Z"
 }
}

Option 2: Poll Payment Intent Endpoint

If you prefer to poll get a payment intent, you can send get request until paymentMethods.address is present.

curl --location --request GET 'https://api-sandbox.circle.com/v1/paymentIntents/{id}' \
--header 'X-Requested-Id: ${GUID}' \
--header 'Authorization: Bearer ${YOUR_API_KEY}'
{
 "data": {
   "id": "6e4d4047-db14-4c09-b238-1215aee50d03",
   "amount": {
     "amount": "1.00",
     "currency": "USD"
   },
   "amountPaid": {
     "amount": "0.00",
     "currency": "USD"
   },
   "settlementCurrency": "USD",
   "paymentMethods": [
     {
       "type": "blockchain",
       "chain": "ETH",
       "address": "0x97de855690955e0da79ce5c1b6804847e7070c7f"
     }
   ],
   "fees": [
     { "type": "blockchainLeaseFee", "amount": "0.00", "currency": "USD" }
   ],
   "paymentIds": [],
   "timeline": [
     { "status": "pending", "time": "2022-07-21T20:13:38.188286Z" },
     { "status": "created", "time": "2022-07-21T20:13:35.579331Z" }
   ],
   "createDate": "2022-07-21T20:13:35.578678Z",
   "updateDate": "2022-07-21T20:13:38.186831Z",
   "expiresOn": "2022-07-21T21:13:38.087275Z"
 }
}

3. Customer Sends Payment On-Chain

Once the deposit address is acquired paymentMethods.address, you will then provide it to the customer along with the amount and currency to be paid. The deposit address can be presented in two forms 1) as plain text that is easily copied 2) as a QR code to be scanned from an app.

From there, the customer will send a payment from their custodial or non-custodial wallet.

📘

The customer must send payment prior to the exipiresOn time is reached.

4. Payment Received

Once Circle receives the payment on-chain, we will create a Payment resource that is associated with the Payment Intent. Additionally, we will update the state of the payment intent. Please see the state management timeline for more details.

Option 1: Webhook Notifications

{
 "clientId": "f1397191-56e6-42fd-be86-0a7b9bd91522",
 "notificationType": "paymentIntents",
 "version": 1,
 "customAttributes": { "clientId": "f1397191-56e6-42fd-be86-0a7b9bd91522" },
 "paymentIntent": {
   "id": "6e4d4047-db14-4c09-b238-1215aee50d03",
   "amount": { "amount": "1.00", "currency": "USD" },
   "amountPaid": { "amount": "1.00", "currency": "USD" },
   "settlementCurrency": "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"],
   "timeline": [
     {
       "status": "complete",
       "context": "paid",
       "time": "2022-07-21T20:19:24.861094Z"
     },
     { "status": "pending", "time": "2022-07-21T20:13:38.188286Z" },
     { "status": "created", "time": "2022-07-21T20:13:35.579331Z" }
   ],
   "createDate": "2022-07-21T20:13:35.578678Z",
   "updateDate": "2022-07-21T20:19:24.859052Z",
   "expiresOn": "2022-07-21T21:13:38.087275Z"
 }
}
{
 "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": "2022-07-21T20:16:35.092Z",
   "updateDate": "2022-07-21T20:19:24.719Z",
   "merchantId": "f1397191-56e6-42fd-be86-0a7b9bd91522",
   "merchantWalletId": "1000999922",
   "paymentIntentId": "6e4d4047-db14-4c09-b238-1215aee50d03",
   "settlementAmount": { "amount": "1.00", "currency": "USD" },
   "depositAddress": {
     "chain": "ETH",
     "address": "0x97de855690955e0da79ce5c1b6804847e7070c7f"
   },
   "transactionHash": "0x7351585460bd657f320b9afa02a52c26d89272d0d10cc29913eb8b28e64fd906"
 }
}

Option 2: Retrieve Payment Intent and Payment

curl --location --request GET 'https://api-sandbox.circle.com/v1/paymentIntents/{id}' \
--header 'X-Requested-Id: ${GUID}' \
--header 'Authorization: Bearer ${YOUR_API_KEY}'
{
 "data": {
   "id": "6e4d4047-db14-4c09-b238-1215aee50d03",
   "amount": {
     "amount": "1.00",
     "currency": "USD"
   },
   "amountPaid": {
     "amount": "1.00",
     "currency": "USD"
   },
   "settlementCurrency": "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"],
   "timeline": [
     {
       "status": "complete",
       "context": "paid",
       "time": "2022-07-21T20:19:24.861094Z"
     },
     {
       "status": "pending",
       "time": "2022-07-21T20:13:38.188286Z"
     },
     {
       "status": "created",
       "time": "2022-07-21T20:13:35.579331Z"
     }
   ],
   "createDate": "2022-07-21T20:13:35.578678Z",
   "updateDate": "2022-07-21T20:19:24.859052Z",
   "expiresOn": "2022-07-21T21:13:38.087275Z"
 }
}
curl --location --request GET 'https://api-sandbox.circle.com/v1/payments/{id}' \
--header 'X-Requested-Id: ${GUID}' \
--header 'Authorization: Bearer ${YOUR_API_KEY}'
{
   "data": {
     "id": "66c56b6a-fc79-338b-8b94-aacc4f0f18de",
     "type": "payment",
     "status": "paid",
     "amount": {
       "amount": "1.00",
       "currency": "USD"
     },
     "fees": {
       "amount": "0.01",
       "currency": "USD"
     },
     "createDate": "2022-07-21T20:16:35.092852Z",
     "updateDate": "2022-07-21T20:19:24.719313Z",
     "merchantId": "f1397191-56e6-42fd-be86-0a7b9bd91522",
     "merchantWalletId": "1000999922",
     "paymentIntentId": "6e4d4047-db14-4c09-b238-1215aee50d03",
     "settlementAmount": {
       "amount": "1.00",
       "currency": "USD"
     },
     "depositAddress": {
       "chain": "ETH",
       "address": "0x97de855690955e0da79ce5c1b6804847e7070c7f"
     },
     "transactionHash": "0x7351585460bd657f320b9afa02a52c26d89272d0d10cc29913eb8b28e64fd906"
   }
 }

Did this page help you?