Accrue Savings Merchant Api Webhooks

generated: '2026-09-06'
method: searched
source: openapi/accrue-savings-merchant-api-openapi.yaml (top-level `webhooks` object, OpenAPI 3.1) and
  https://docs.byaccrue.com/docs/webhooks/
docs: https://docs.byaccrue.com/docs/webhooks/
asyncapi:
  published: false
  note: Accrue publishes NO AsyncAPI document. Its event surface is described inside the OpenAPI 3.1 `webhooks`
    object — the modern OpenAPI way to do this — with a full request schema per topic. That is a real
    machine-readable event contract; it is simply not AsyncAPI, so no asyncapi spec file is saved and
    none is fabricated.
delivery: HTTP POST to a merchant-registered endpoint, body application/vnd.api+json in the JSON:API document
  shape (data + included).
management_api:
  operations:
  - createWebhook
  - getWebhooks
  - getWebhook
  - updateWebhook
  - deleteWebhook
  - listWebhookEvents
  - getWebhookEvent
  note: Subscriptions are managed through the API itself, and delivered events are queryable after the
    fact via listWebhookEvents / getWebhookEvent — a replay/audit surface many providers omit. Subscribing
    with the "*" wildcard means new topics arrive automatically, which Accrue calls out in its changelog.
security:
  mechanism: signature verification
  documented: partially
  note: The getting-started guide says to always verify webhook signatures using a constant-time comparison,
    but neither the signing header name, the algorithm, nor the secret-provisioning flow is published
    publicly. An integrator cannot implement verification from the public docs alone.
topic_count: 20
topics:
- topic: paymentIntentCreated
  event: PaymentIntentCreated
  method: POST
  description: null
- topic: paymentIntentUpdated
  event: PaymentIntentUpdated
  method: POST
  description: null
- topic: paymentCreated
  event: PaymentCreated
  method: POST
  description: null
- topic: paymentUpdated
  event: PaymentUpdated
  method: POST
  description: null
- topic: paymentCaptured
  event: PaymentCaptured
  method: POST
  description: null
- topic: refundCreated
  event: RefundCreated
  method: POST
  description: null
- topic: refundUpdated
  event: RefundUpdated
  method: POST
  description: null
- topic: kycCreated
  event: KycCreated
  method: POST
  description: Fired when a KYC application is created for a user. This event is triggered when a user
    initiates the identity verification process.
- topic: kycApproved
  event: KycApproved
  method: POST
  description: Fired when a KYC application is approved. This event indicates that the user has successfully
    passed identity verification and can access banking features.
- topic: kycDeclined
  event: KycDeclined
  method: POST
  description: Fired when a KYC application is declined. This event indicates that the user did not pass
    identity verification and cannot access banking features.
- topic: kycAwaitingDocuments
  event: KycAwaitingDocuments
  method: POST
  description: Fired when a KYC application requires additional document verification. This event indicates
    that the user needs to upload identity documents (such as a driver's license or passport) to complete
    verification.
- topic: kycPending
  event: KycPending
  method: POST
  description: Fired when a KYC application is pending review. This event indicates that the application
    is being processed through automated verification checks.
- topic: kycManualReview
  event: KycManualReview
  method: POST
  description: Fired when a KYC application requires manual review. This event indicates that automated
    verification could not make a determination and the application needs human review.
- topic: transactionCleared
  event: Transaction Cleared
  method: POST
  description: Fired when a transaction is cleared. This event indicates that the transaction has been
    successfully processed and funds are available. The included payload contains event data with a **fee**
    object (fee type and amount in cents).
- topic: transactionFailed
  event: Transaction Failed
  method: POST
  description: 'Fired when a transaction fails. This event indicates that the transaction could not be
    processed successfully. The included payload contains event data with a **fee** object (fee type and
    amount in cents) and **failureReason** (TransactionFailureReason: e.g. Canceled, HardDecline, SoftDecline,
    Expired, InsufficientFunds, Reversed, Unknown).'
- topic: counterpartyIncomingPayment
  event: CounterpartyIncomingPayment
  method: POST
  description: 'Fired when a payment arrives on a counterparty''s bank account and has been recorded on
    the counterparty''s balance. Use this to reconcile funding you receive from a counterparty over bank
    rails without polling the counterparty balance.


    The included payload carries **counterpartyId**, **amount** (in cents), **currency**, **direction**
    (`credit` for funds received, `debit` for funds withdrawn), **method** (the bank rail, for example
    `ach` or `wire`), **asOfDate** (the bank settlement date), and **externalIncomingPaymentId** for reconciliation
    against your bank records.


    This event is only sent after the payment has been recorded, so the counterparty balance already reflects
    it when you receive the webhook.'
- topic: counterpartyPayoutCreated
  event: CounterpartyPayoutCreated
  method: POST
  description: 'Fired when a payout is created for a counterparty and submitted for processing. `status`
    is the payout''s initial state, which may be `Approved`, `NeedsApproval`, or `Processing` depending
    on your approval configuration.


    A duplicate create — the same idempotency key replayed — returns the existing payout and does **not**
    fire a second event.


    The included payload mirrors the payout resource — **payoutId**, **counterpartyId**, **amount** (in
    cents), **currency**, **status**, **description**, and **effectiveDate** — so you can act on the event
    without re-reading the payouts API.'
- topic: counterpartyPayoutSent
  event: CounterpartyPayoutSent
  method: POST
  description: 'Fired when the payout has been sent to the bank. The funds have left, but the payment
    is not yet reconciled — a payout can sit in this state for a few days depending on the rail, and can
    still be returned afterwards. Wait for `CounterpartyPayoutCompleted` before treating the money as
    delivered.


    The included payload mirrors the payout resource — **payoutId**, **counterpartyId**, **amount** (in
    cents), **currency**, **status**, **description**, and **effectiveDate** — so you can act on the event
    without re-reading the payouts API.'
- topic: counterpartyPayoutCompleted
  event: CounterpartyPayoutCompleted
  method: POST
  description: 'Fired when the payout has been reconciled to a posted bank transaction. This is the terminal
    success state: the funds have settled at the receiving bank.


    The included payload mirrors the payout resource — **payoutId**, **counterpartyId**, **amount** (in
    cents), **currency**, **status**, **description**, and **effectiveDate** — so you can act on the event
    without re-reading the payouts API.'
- topic: counterpartyPayoutReturned
  event: CounterpartyPayoutReturned
  method: POST
  description: 'Fired when a payout ends without delivering funds. This covers every terminal failure
    — returned, reversed, cancelled, denied, and failed — so read **status** to see which occurred rather
    than relying on the topic name.


    **returnCode** and **returnReason** are populated when the receiving bank returned the payment (for
    example `R01`, insufficient funds) and are null for the other failures. The payout amount is available
    on the counterparty balance again.


    The included payload mirrors the payout resource — **payoutId**, **counterpartyId**, **amount** (in
    cents), **currency**, **status**, **description**, and **effectiveDate** — so you can act on the event
    without re-reading the payouts API.'
error_codes:
- InvalidTopics (400) on webhook registration
- WebhookNotFoundResponse (404)