Webhook Notifications

Circle Mint delivers webhook notifications as AWS SNS messages to an HTTPS endpoint you register. Every topic shares a common envelope; the inner resource varies by topic. If you do not have a Circle Mint account, start with the Getting Started quickstart.

Set up your endpoint

Your subscriber endpoint must be publicly reachable over HTTPS and handle both HEAD and POST requests. Circle issues HEAD requests as a connectivity warmup; webhook deliveries arrive as POST requests with the AWS SNS payload in the request body.

Subscribe your endpoint

Receive the subscription confirmation

Circle sends a POST with Type: SubscriptionConfirmation to your endpoint. The body includes a SubscribeURL that you must visit to finish the handshake.

Confirm the subscription

Open the SubscribeURL from the message body. The subscription status moves to confirmed and Circle begins delivering notifications.

For local development, point your subscription at a webhook.site URL. Open the message body, copy the SubscribeURL, and paste it into your browser to confirm the subscription.

Example SubscriptionConfirmation payload

{
  "Type": "SubscriptionConfirmation",
  "MessageId": "ddbdcdcf-d36a-45b5-927c-da25b9b009ae",
  "Token": "2336412f37fb687f5d51e6e2425f004aed7b7526d5fae41bc257a0d80532a6820258bf77eb25b90453b863450713a2a5a4250696d725a306ef39962b5b543752c9003e0841c0e61253fd6c517a94edebe44f36c5fe4ba131c8ea5f6f42a43f97f6e1865505e2f29f79a62f89e18f97e03a0dd5d982a7578c8d6e21154163f2d6aae523cff25557f9bc21b2503d413006",
  "TopicArn": "arn:aws:sns:us-west-2:908968368384:sandbox_platform-notifications-topic",
  "Message": "You have chosen to subscribe to the topic arn:aws:sns:us-west-2:908968368384:sandbox_platform-notifications-topic.\nTo confirm the subscription, visit the SubscribeURL included in this message.",
  "SubscribeURL": "https://sns.us-west-2.amazonaws.com/?Action=ConfirmSubscription&TopicArn=arn:aws:sns:us-west-2:908968368384:sandbox_platform-notifications-topic&Token=2336412f37fb687f5d51e6e2425f004aed7b7526d5fae41bc257a0d80532a6820258bf77eb25b90453b863450713a2a5a4250696d725a306ef39962b5b543752c9003e0841c0e61253fd6c517a94edebe44f36c5fe4ba131c8ea5f6f42a43f97f6e1865505e2f29f79a62f89e18f97e03a0dd5d982a7578c8d6e21154163f2d6aae523cff25557f9bc21b2503d413006",
  "Timestamp": "2020-04-11T20:50:16.324Z",
  "SignatureVersion": "1",
  "Signature": "kBr9z/ysQrr0ldowHY4lThkOA+dwyjcsyx7NwkbTkgEKG4N61BSSEA+43aYQEB/Ml09hclybvyjyRKWYOjaxQgbUXWmyWrCQ7vY93WYhuGvOqZxAMPiDiILxLs6/KtOxneKVvzfpK4abLrYyTTA+z/dQ52h9L8eoiSKSW81e4clfYBTJkGmuAPKFC08FvEAVT89VikPp68mBf4CctPv3Em0b4J1VvDhAB21B2LekgUmwUE0aE7fUbsF3XsKGQd/fDshLOJasQEuXSqdB5X7LITBA8r24FY+wCjwm8oR3VI9IMy21fUC6wMgoFIVZHW1KxzpEkMCSe7R1ySdNIru8SQ==",
  "SigningCertURL": "https://sns.us-west-2.amazonaws.com/SimpleNotificationService-a86cb10b4e1f29c941702d737128f7b6.pem"
}

You can register a subscription through the Circle Mint console or by calling the Subscriptions API directly.

Via the Mint console

In the Circle Mint console, navigate to Developer → Subscriptions.
Click Add Subscription.
Paste your HTTPS endpoint URL.
Click Save to submit the subscription. Circle delivers a SubscriptionConfirmation to the endpoint; confirm it as described in Set up your endpoint.

Via the API

Call POST /v1/notifications/subscriptions with the endpoint URL:

curl -X POST https://api-sandbox.circle.com/v1/notifications/subscriptions \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"endpoint":"https://example.com/webhooks/circle"}'

The response returns the subscription id, the registered endpoint, and a subscriptionDetails[] array. Each element carries the SNS topic url, the topic arn, and a status of confirmed, pending, or deleted.

{
  "data": {
    "id": "b8627ae8-732b-4d25-b947-1df8f4007a29",
    "endpoint": "https://example.com/webhooks/circle",
    "subscriptionDetails": [
      {
        "url": "arn:aws:sns:us-west-2:908968368384:sandbox_platform-notifications-topic",
        "arn": "arn:aws:sns:us-west-2:908968368384:sandbox_platform-notifications-topic:fcb4a2c9-9c4f-4706-b312-6b22650f5d17",
        "status": "pending"
      }
    ]
  }
}

Manage subscriptions

List active subscriptions with GET /v1/notifications/subscriptions and remove one with DELETE /v1/notifications/subscriptions/{id}. A subscription can be deleted only when every entry in subscriptionDetails[] is confirmed, deleted, or a mix of the two. A subscription with any pending entry cannot be deleted; resolve the pending state first.

Environment	Active subscription cap	`PENDING` auto-removal
Sandbox	3	After 30 days
Production	1	After 72 hours

Notification envelope

Every Mint webhook arrives as an AWS SNS HTTPS notification. The SNS envelope wraps a Circle-shaped message in its Message field, which is delivered as a JSON string. Parse Message to access the Circle envelope and the topic-specific resource it carries. The outer SNS envelope has the following shape:

{
  "Type": "Notification",
  "MessageId": "22b80b92-fdea-4c2c-8f9d-bdfb0c7bf324",
  "TopicArn": "arn:aws:sns:us-west-2:908968368384:sandbox_platform-notifications-topic",
  "Subject": "deposits",
  "Message": "{\"clientId\":\"00000000-0000-0000-0000-000000000000\",\"notificationType\":\"deposits\",\"version\":1,\"deposit\":{ ... }}",
  "Timestamp": "2026-01-15T18:23:44.911Z",
  "SignatureVersion": "1",
  "Signature": "EXAMPLElDMXvB8r9R83tGoNn0ecuGq3aV4mZ+gQv5jb2FQ...",
  "SigningCertURL": "https://sns.us-west-2.amazonaws.com/SimpleNotificationService-a86cb10b4e1f29c941702d737128f7b6.pem",
  "UnsubscribeURL": "https://sns.us-west-2.amazonaws.com/?Action=Unsubscribe&SubscriptionArn=arn:aws:sns:us-west-2:908968368384:sandbox_platform-notifications-topic:fcb4a2c9-9c4f-4706-b312-6b22650f5d17",
  "MessageAttributes": {
    "clientId": {
      "Type": "String",
      "Value": "00000000-0000-0000-0000-000000000000"
    }
  }
}

The inner Circle envelope, parsed from Message, has the following shape:

{
  "clientId": "00000000-0000-0000-0000-000000000000",
  "notificationType": "deposits",
  "version": 1,
  "customAttributes": { "clientId": "00000000-0000-0000-0000-000000000000" },
  "deposit": { "...": "topic-specific resource" }
}

The following attributes appear on every Circle envelope:

Name	Type	Description
`clientId`	`string` (UUIDv4)	Identifier for the Circle Mint account that owns the resource.
`notificationType`	`string`	The webhook topic. Matches one of the topics in Event types.
`version`	`int`	Schema version for the notification payload.
`customAttributes`	`object`	Echoes selected envelope attributes. The `clientId` field mirrors the top-level `clientId` value.

The remaining keys on the envelope vary by topic—for example, deposit, payout, transfer, or paymentIntent—and carry the resource the topic describes.

Event types

The table below lists every Circle Mint webhook topic and the resource each notification carries. The subsections that follow describe each topic, document its status values when applicable, and show a single example payload.

Topic	Resource	What it reports
`wire`	Wire bank account	Lifecycle of a linked wire bank account: `pending`, `complete`, or `failed`.
`deposits`	Deposit	Settlement of a fiat deposit (mint) to your Circle Mint balance.
`payouts`	Payout	Lifecycle of a fiat redemption (burn) or stablecoin payout.
`transfers`	Transfer	Onchain transfer status transitions in either direction.
`paymentIntents`	Payment intent	Stablecoin Payins intent lifecycle, including deposit-address assignment and timeline events.
`payments`	Payment	Settled Stablecoin Payins payment, or a Stablecoin Payouts refund.
`addressBookRecipients`	Address book recipient	Recipient review outcome and Travel Rule decision for Stablecoin Payouts.
`externalEntities`	External entity	Core API for Institutions compliance outcome for an onboarded entity.
`creditTransfers`	Credit transfer	Status transitions for a Settlement Advance or Line of Credit draw.
`creditFees`	Credit fee	Fee accruals against a credit line.
`creditRepayments`	Credit repayment	Matched fiat repayment or completed crypto repayment against a credit line.
`approvalWorkflowTransferApproved`	Approval workflow event	A pending transfer was approved through the recipient approval workflow.
`approvalWorkflowTransferRejected`	Approval workflow event	A pending transfer was rejected through the recipient approval workflow.

`wire`

Lifecycle notifications for a linked wire bank account. Use these events to track the status of bank-account creation requests submitted through POST /v1/businessAccount/banks/wires.

Status	Meaning
`pending`	Circle is reviewing the bank account.
`complete`	The bank account is linked and can be used for deposits and payouts.
`failed`	The bank account could not be linked.

Example payload

{
  "clientId": "00000000-0000-0000-0000-000000000001",
  "notificationType": "wire",
  "version": 1,
  "customAttributes": { "clientId": "00000000-0000-0000-0000-000000000001" },
  "wire": {
    "id": "8c33b3eb-67a4-4f3d-9f4e-2d8a4f1c2b6a",
    "status": "complete",
    "description": "WELLS FARGO BANK, NA ****0010",
    "trackingRef": "CIR2VKZ9G6",
    "fingerprint": "eb74e904-2c64-4f4d-9f54-9f1b8f7a2bb1",
    "billingDetails": {
      "name": "Satoshi Nakamoto",
      "city": "Boston",
      "country": "US",
      "line1": "100 Money Street",
      "district": "MA",
      "postalCode": "02201"
    },
    "createDate": "2026-01-15T18:23:44.000Z",
    "updateDate": "2026-01-15T18:25:11.000Z"
  }
}

`deposits`

Fires when a fiat deposit (mint) settles to your Circle Mint balance. The notification carries the deposit id, the settled amount, the source (the linked wire bank account), and the destination wallet.

Status	Meaning
`pending`	Circle has received the wire and is processing the mint.
`complete`	USDC or EURC has been credited to the destination wallet.
`failed`	The deposit could not be completed and funds were not credited.

When the originating wire memo included a customerExternalRef matching the EXT... format (used by the Core API for Institutions), Circle echoes that value on the deposit so you can reconcile the credit to the originating client.

Example payload

{
  "clientId": "00000000-0000-0000-0000-000000000001",
  "notificationType": "deposits",
  "version": 1,
  "customAttributes": { "clientId": "00000000-0000-0000-0000-000000000001" },
  "deposit": {
    "id": "df3b8e5f-9579-4c1f-9fa9-deac7f4be55c",
    "status": "complete",
    "amount": { "amount": "1000.00", "currency": "USD" },
    "fees": { "amount": "0.00", "currency": "USD" },
    "source": { "id": "8c33b3eb-67a4-4f3d-9f4e-2d8a4f1c2b6a", "type": "wire" },
    "destination": { "id": "1000038499", "type": "wallet" },
    "customerExternalRef": "EXT0000000000000000A1",
    "createDate": "2026-01-15T18:23:44.000Z",
    "updateDate": "2026-01-15T18:26:02.000Z"
  }
}

`payouts`

Fires for fiat redemptions (burns) and stablecoin payouts. The payout resource carries the destination (a wire bank account or an address_book recipient), the gross amount, fees, and any error information. The most important fields to consume:

id: Unique payout identifier.
destination: Either a wire destination (fiat redemption) or an address_book destination (stablecoin payout).
amount: Gross amount of the payout, as a money object.
toAmount: Net amount delivered to the destination. Present only on stablecoin payouts.
trackingRef: Reference that appears on the bank statement. Present on fiat redemption (burn) payouts.
sourceWalletId: Identifier of the wallet funding the payout.
fees: Fees deducted from the source wallet, as a money object.
networkFees: Onchain network fees. Present only on stablecoin payouts.
status: pending, complete, or failed.
errorCode: Populated when status is failed. See Stablecoin Payouts errors for the catalog.
riskEvaluation: Risk decision and reason, populated for compliance-driven denials.

Status	Meaning
`pending`	The payout is in progress.
`complete`	Funds have been delivered to the destination.
`failed`	The payout could not be completed. See `errorCode` for the reason.

Example payload

{
  "clientId": "00000000-0000-0000-0000-000000000001",
  "notificationType": "payouts",
  "version": 1,
  "customAttributes": { "clientId": "00000000-0000-0000-0000-000000000001" },
  "payout": {
    "id": "df3b8e5f-9579-4c1f-9fa9-deac7f4be55c",
    "sourceWalletId": "1000038499",
    "destination": {
      "id": "4d260293-d17c-4309-a8da-fa7850f95c10",
      "type": "address_book"
    },
    "amount": { "amount": "100.00", "currency": "USD" },
    "toAmount": { "amount": "100.00", "currency": "USD" },
    "fees": { "amount": "0.50", "currency": "USD" },
    "networkFees": { "amount": "0.10", "currency": "USD" },
    "trackingRef": "CIR2VKZ9G6",
    "status": "complete",
    "riskEvaluation": { "decision": "approved", "reason": "1000" },
    "createDate": "2026-01-15T18:23:44.000Z",
    "updateDate": "2026-01-15T18:26:02.000Z"
  }
}

`transfers`

Fires on every status transition for an onchain transfer, in either direction (Circle wallet to blockchain address, blockchain address to Circle wallet, or wallet to wallet). You receive one notification per transition, so a transfer that runs to completion produces multiple events.

Status	Meaning
`pending`	The transfer has been submitted and is awaiting onchain broadcast.
`running`	The transfer is broadcast and waiting for confirmations.
`complete`	The transfer is confirmed onchain and settled.
`failed`	The transfer could not be completed. See `errorCode` for the reason.

When status is failed, the transfer carries an errorCode; see Transfer entity errors for the catalog.

Example payload

{
  "clientId": "00000000-0000-0000-0000-000000000001",
  "notificationType": "transfers",
  "version": 1,
  "customAttributes": { "clientId": "00000000-0000-0000-0000-000000000001" },
  "transfer": {
    "id": "0d46b642-3a5f-4071-a747-4053b7df2f99",
    "source": { "type": "wallet", "id": "1000038499" },
    "destination": {
      "type": "blockchain",
      "address": "0x8381470ED67C3802402dbbFa0058E8871F017A6F",
      "chain": "ARC"
    },
    "amount": { "amount": "3.14", "currency": "USD" },
    "transactionHash": "0x4cebf8f90c9243a23c77e4ae20df691469e4b933b295a73376292843968f7a63",
    "status": "complete",
    "riskEvaluation": { "decision": "approved", "reason": "1000" },
    "createDate": "2026-01-15T18:23:44.000Z"
  }
}

`paymentIntents`

Fires on lifecycle changes for a Stablecoin Payins payment intent, including deposit-address assignment, settlement, expiry, refund, and failure. The payload includes the intent’s full state—paymentMethods[] (the assigned deposit addresses), timeline[] (an ordered history of status and context transitions with timestamps), amountPaid, amountRefunded, settlementCurrency, and fees[]. The intent’s lifecycle depends on type:

continuous intents stay at active after Circle assigns the deposit address and never advance to complete. To reconcile settled transfers against a continuous intent, listen to the payments topic or call GET /v1/payments with paymentIntentId={id}.
transient intents move through created → pending → complete, where the latest timeline[] entry carries a context of paid, underpaid, or overpaid. Terminal states are expired, failed, and refunded.

For background on intent modes and the payin flow, see How Stablecoin Payins and Payouts work.

Example payload

{
  "clientId": "00000000-0000-0000-0000-000000000001",
  "notificationType": "paymentIntents",
  "version": 1,
  "customAttributes": { "clientId": "00000000-0000-0000-0000-000000000001" },
  "paymentIntent": {
    "id": "5cb31987-66f1-4ce6-87ce-fb74dfe7c2dd",
    "type": "continuous",
    "amount": { "amount": "0.00", "currency": "USD" },
    "amountPaid": { "amount": "0.00", "currency": "USD" },
    "amountRefunded": { "amount": "0.00", "currency": "USD" },
    "settlementCurrency": "USD",
    "paymentMethods": [
      {
        "type": "blockchain",
        "chain": "ARC",
        "address": "0x8381470ED67C3802402dbbFa0058E8871F017A6F"
      }
    ],
    "fees": [],
    "timeline": [
      { "status": "active", "time": "2026-01-15T18:23:44.000Z" },
      { "status": "created", "time": "2026-01-15T18:23:40.000Z" }
    ],
    "createDate": "2026-01-15T18:23:40.000Z",
    "updateDate": "2026-01-15T18:23:44.000Z"
  }
}

`payments`

Fires for inbound Stablecoin Payins settlements and for Stablecoin Payouts refunds. Both flows use the same payments resource; the type field discriminates between them: payment for an inbound settlement and refund for an outbound refund.

Status	Meaning
`pending`	The payment has been observed and is awaiting confirmations.
`confirmed`	The payment has reached the required number of onchain confirmations.
`paid`	The payment has settled to your Circle Mint balance.
`failed`	The payment could not be settled.
`action_required`	Manual intervention is required, such as a refund decision on an underpayment.

Example payment payload

{
  "clientId": "00000000-0000-0000-0000-000000000001",
  "notificationType": "payments",
  "version": 1,
  "customAttributes": { "clientId": "00000000-0000-0000-0000-000000000001" },
  "payment": {
    "id": "b9aef7d4-2eb4-4f4a-9b7f-71b3a4c9bb3b",
    "type": "payment",
    "status": "paid",
    "paymentIntentId": "5cb31987-66f1-4ce6-87ce-fb74dfe7c2dd",
    "amount": { "amount": "250.00", "currency": "USD" },
    "feeAmount": { "amount": "0.50", "currency": "USD" },
    "source": {
      "type": "blockchain",
      "chain": "ARC",
      "address": "0x6E1A4C16fAFC4ec1Aa1Dc6Fbe5cE9aB2B22B3F11"
    },
    "depositAddress": {
      "chain": "ARC",
      "address": "0x8381470ED67C3802402dbbFa0058E8871F017A6F"
    },
    "transactionHash": "0x4cebf8f90c9243a23c77e4ae20df691469e4b933b295a73376292843968f7a63",
    "createDate": "2026-01-15T18:23:44.000Z",
    "updateDate": "2026-01-15T18:25:11.000Z"
  }
}

Example refund payload

{
  "clientId": "00000000-0000-0000-0000-000000000001",
  "notificationType": "payments",
  "version": 1,
  "customAttributes": { "clientId": "00000000-0000-0000-0000-000000000001" },
  "payment": {
    "id": "c12ab9d6-3fc7-4ec1-92d4-58c1a4d5fae2",
    "type": "refund",
    "status": "paid",
    "paymentIntentId": "5cb31987-66f1-4ce6-87ce-fb74dfe7c2dd",
    "originalPaymentId": "b9aef7d4-2eb4-4f4a-9b7f-71b3a4c9bb3b",
    "amount": { "amount": "250.00", "currency": "USD" },
    "settlementAmount": { "amount": "250.00", "currency": "USD" },
    "destination": {
      "type": "blockchain",
      "chain": "ARC",
      "address": "0x6E1A4C16fAFC4ec1Aa1Dc6Fbe5cE9aB2B22B3F11"
    },
    "transactionHash": "0x9fbe04f70cb1d5f5c12c93dcb2e21a8d6c3b8a4f93e1c01e2c3a4b5c6d7e8f90",
    "createDate": "2026-01-15T19:02:11.000Z",
    "updateDate": "2026-01-15T19:04:48.000Z"
  }
}

`addressBookRecipients`

Fires on lifecycle transitions for a Stablecoin Payouts recipient registered through the Address Book API. Use this topic to learn when a recipient is ready to receive payouts and to handle Travel Rule decisions on counterparties.

Status	Meaning
`pending`	Circle is reviewing the recipient.
`inactive`	The recipient is in the delayed-withdrawals holding period.
`active`	The recipient is ready to receive payouts.
`denied`	The recipient failed review and cannot receive payouts.

For Travel Rule requirements and identity schemas that influence these decisions, see Travel Rule Compliance.

Example payload

{
  "clientId": "00000000-0000-0000-0000-000000000001",
  "notificationType": "addressBookRecipients",
  "version": 1,
  "customAttributes": { "clientId": "00000000-0000-0000-0000-000000000001" },
  "addressBookRecipient": {
    "id": "4d260293-d17c-4309-a8da-fa7850f95c10",
    "status": "active",
    "chain": "ARC",
    "address": "0x8381470ED67C3802402dbbFa0058E8871F017A6F",
    "nickname": "Vendor wallet",
    "metadata": {
      "nickname": "Vendor wallet",
      "type": "business"
    },
    "createDate": "2026-01-15T18:23:44.000Z",
    "updateDate": "2026-01-15T18:26:02.000Z"
  }
}

`externalEntities`

Fires when Circle finishes its compliance review for an external entity onboarded through the Institutional API. The webhook carries the final complianceState decision; walletId is present only when the decision is ACCEPTED.

`complianceState`	Meaning
`PENDING`	The entity is under review. The accompanying `walletId` is unusable.
`ACCEPTED`	The entity passed review. The accompanying `walletId` is provisioned and usable.
`REJECTED`	The entity failed review and cannot operate through Circle Mint.

For background on the onboarding flow and how to use a provisioned walletId, see Institutional API and Manage Institutional Subaccounts.

Example payload

{
  "clientId": "00000000-0000-0000-0000-000000000001",
  "notificationType": "externalEntities",
  "version": 1,
  "customAttributes": { "clientId": "00000000-0000-0000-0000-000000000001" },
  "externalEntity": {
    "id": "9a4d6e72-78aa-4b9d-bd84-2cc7c1a8c2d4",
    "complianceState": "ACCEPTED",
    "walletId": "212000",
    "businessName": "Example Trading Ltd.",
    "businessUniqueIdentifier": "TAX-001",
    "identifierIssuingCountryCode": "US",
    "createDate": "2026-01-15T18:23:44.000Z",
    "updateDate": "2026-01-15T18:30:00.000Z"
  }
}

`creditTransfers`

Fires when a credit draw changes status. The two Credit API products follow different lifecycles, so the meaningful status values depend on which product the credit line is scoped to. Settlement Advance status values:

Status	Meaning
`funds_reserved`	Capacity is reserved against the credit line; the reservation expires in 30 minutes.
`requested`	Wire proof has been submitted and Treasury is reviewing the request.
`disbursed`	Treasury approved the advance and funds have landed.
`paid`	The disbursed amount is fully repaid.
`past_due`	The disbursed amount has not been fully repaid by its due date.
`expired`	The reservation timed out before progressing to `requested`.
`canceled`	You canceled the reservation before submitting wire proof.
`rejected`	Treasury declined the request.

Line of Credit status values:

Status	Meaning
`requested`	The draw was created and is being processed for disbursement.
`disbursed`	Funds have landed in your Mint wallet or at the verified Credit Express destination.
`paid`	The disbursed amount is fully repaid.
`past_due`	The disbursed amount has not been fully repaid by its due date.
`rejected`	Circle declined the request.

When a transfer is configured with a Credit Express destination, the disbursement carries an additional onchain delivery status:

Credit Express destination status	Meaning
`pending`	The onchain delivery has not started.
`initiated`	The onchain transaction has been broadcast.
`complete`	The onchain delivery is confirmed.
`failed`	The onchain delivery failed.

For background on the credit-line model and the two product lifecycles, see the Credit API concept.

Example payload

{
  "clientId": "00000000-0000-0000-0000-000000000001",
  "notificationType": "creditTransfers",
  "version": 1,
  "customAttributes": { "clientId": "00000000-0000-0000-0000-000000000001" },
  "creditTransfer": {
    "id": "c3a2f1e0-7e8c-4b3d-9b9b-1f4e2a7d4c11",
    "product": "lineOfCredit",
    "status": "disbursed",
    "amount": { "amount": "50000.00", "currency": "USD" },
    "outstandingAmount": { "amount": "50000.00", "currency": "USD" },
    "destination": { "type": "wallet", "id": "1000038499" },
    "disbursedAt": "2026-01-15T18:23:44.000Z",
    "dueAt": "2026-01-22T18:23:44.000Z",
    "createDate": "2026-01-15T18:23:00.000Z",
    "updateDate": "2026-01-15T18:23:44.000Z"
  }
}

`creditFees`

Fires when a fee accrues against a credit line. Cadence matches the credit line’s feeCadence: daily lines emit a fee notification every 24 hours and hourly Line of Credit lines emit one every hour. Each notification carries the accrued amount, the credit line it applies to, and the period it covers.

Example payload

{
  "clientId": "00000000-0000-0000-0000-000000000001",
  "notificationType": "creditFees",
  "version": 1,
  "customAttributes": { "clientId": "00000000-0000-0000-0000-000000000001" },
  "creditFee": {
    "id": "fee-1ef1f5cf-2b1b-4f12-aa6c-2c4f9b8fb3da",
    "creditLineId": "9c2c5f4d-1b6c-4a5f-9d0e-3a4b5c6d7e8f",
    "creditTransferId": "c3a2f1e0-7e8c-4b3d-9b9b-1f4e2a7d4c11",
    "type": "recurringFee",
    "amount": { "amount": "50.00", "currency": "USD" },
    "feeCadence": "daily",
    "periodStart": "2026-01-15T18:23:44.000Z",
    "periodEnd": "2026-01-16T18:23:44.000Z",
    "createDate": "2026-01-16T18:23:44.000Z"
  }
}

`creditRepayments`

Fires when Circle matches an incoming fiat wire to a credit line or records a completed crypto repayment. The payload identifies the credit line, the repayment method (fiat or crypto), the matched amount, and the resulting outstanding balance.

Example payload

{
  "clientId": "00000000-0000-0000-0000-000000000001",
  "notificationType": "creditRepayments",
  "version": 1,
  "customAttributes": { "clientId": "00000000-0000-0000-0000-000000000001" },
  "creditRepayment": {
    "id": "rep-3c8d9e0f-1a2b-4c5d-6e7f-8a9b0c1d2e3f",
    "creditLineId": "9c2c5f4d-1b6c-4a5f-9d0e-3a4b5c6d7e8f",
    "creditTransferId": "c3a2f1e0-7e8c-4b3d-9b9b-1f4e2a7d4c11",
    "type": "fiat",
    "status": "complete",
    "amount": { "amount": "50050.00", "currency": "USD" },
    "outstandingAmount": { "amount": "0.00", "currency": "USD" },
    "createDate": "2026-01-22T16:00:00.000Z",
    "updateDate": "2026-01-22T16:05:00.000Z"
  }
}

`approvalWorkflowTransferApproved` and `approvalWorkflowTransferRejected`

Recipient approval workflow events. Some regions require a separate approval step before a transfer can proceed; France and Singapore are two examples. Pending transfers are routed to an approver. The decision is delivered on approvalWorkflowTransferApproved when the proposal is approved or on approvalWorkflowTransferRejected when it is rejected. The payload carries the proposal’s transferStatus, proposalStatus, the originating idempotencyKey, and the transferId of the affected transfer.

Example payload

{
  "clientId": "00000000-0000-0000-0000-000000000001",
  "notificationType": "approvalWorkflowTransferApproved",
  "version": 1,
  "customAttributes": { "clientId": "00000000-0000-0000-0000-000000000001" },
  "approvalWorkflow": {
    "transferId": "0d46b642-3a5f-4071-a747-4053b7df2f99",
    "transferStatus": "pending",
    "proposalStatus": "approved",
    "idempotencyKey": "ba943ff1-ca16-49b2-ba55-1057e70ca5c7",
    "createDate": "2026-01-15T18:23:44.000Z",
    "updateDate": "2026-01-15T18:28:00.000Z"
  }
}

​Set up your endpoint

​Subscribe to webhooks

​Via the Mint console

​Via the API

​Manage subscriptions

​Notification envelope

​Event types

​wire

​deposits

​payouts

​transfers

​paymentIntents

​payments

​addressBookRecipients

​externalEntities

​creditTransfers

​creditFees

​creditRepayments

​approvalWorkflowTransferApproved and approvalWorkflowTransferRejected

Set up your endpoint

Subscribe to webhooks

Via the Mint console

Via the API

Manage subscriptions

Notification envelope

Event types

`wire`

`deposits`

`payouts`

`transfers`

`paymentIntents`

`payments`

`addressBookRecipients`

`externalEntities`

`creditTransfers`

`creditFees`

`creditRepayments`

`approvalWorkflowTransferApproved` and `approvalWorkflowTransferRejected`