Flywire Payments Webhooks

generated: '2026-09-02'
method: searched
source: https://developers.flywire.com/education/Content/notifications-payment-status.htm
also_documented_at: https://solutions.flywire.com/en/webhooks/notifications-v2
spec_type: Webhooks
notes: >-
  Flywire documents webhook callbacks ("Payment Status Notifications") but does
  not publish a machine-readable AsyncAPI document, so this captures the webhook
  event catalog rather than an AsyncAPI spec. For each payment status change the
  Flywire platform sends a POST (JSON) to the merchant-registered callback URL.
delivery:
  transport: https-webhook
  method: POST
  content_type: application/json
  callback_url: >-
    Publicly reachable URL registered per application, or per-payment via the
    notifications_url field on payment creation.
  signature:
    header: X-Flywire-Digest
    algorithm: base64-encoded HMAC-SHA256 of the request body using the Shared Secret
    secret: Shared Secret issued at application registration
envelope_fields:
- event_type
- event_date
- event_resource
- data
data_fields:
- payment_id
- amount_from
- currency_from
- amount_to
- currency_to
- status
- expiration_date
- external_reference
- country
- payment_method
- fields
- payer
events:
- type: initiated
  resource: payment
  description: New payment created.
- type: processed
  resource: payment
  description: Funds received or captured.
- type: guaranteed
  resource: payment
  description: Funds validated and guaranteed.
- type: delivered
  resource: payment
  description: Funds disbursed in batch.
- type: cancelled
  resource: payment
  description: Payment will not process.
- type: reversed
  resource: payment
  description: Refund completed (direct debit only).
- type: authorized
  resource: charge
  description: Pre-authorization hold placed.
- type: adjusted
  resource: charge
  description: Pre-authorization amount modified.
- type: failed
  resource: charge
  description: Capture issue occurred.

callback_version:
  current: '2'
  selected_by: The callbackVersion parameter in the Checkout configuration.
  v1_status: deprecated
  v1_docs: https://solutions.flywire.com/en/webhooks/notifications-v1
  note: >-
    Flywire's Solutions documentation carries "Payment Notifications v.1" under an
    explicit "Deprecated" navigation section, and v2 is the documented current
    version. Added 2026-09-02 from solutions.flywire.com, which developers.flywire.com
    does not mention.
  source: https://solutions.flywire.com/en/webhooks/notifications-v2
retry_policy:
  automatic_retries: 3
  schedule_seconds: [180, 1800, 10800]
  schedule_human: ['3 minutes', '30 minutes', '3 hours']
  after_final_retry: Not documented.
  source: https://solutions.flywire.com/en/webhooks/notifications-v2
failure_details:
  event: failed
  fields: [reason, reason_code]
  note: >-
    The failed event carries a reason and a reason_code describing the collection
    problem. Flywire does not publish an enumerated registry of reason_code values
    anywhere in its documentation, so a consumer cannot map a code to a remediation
    without asking Flywire — see the note in errors/flywire-problem-types.yml.
  source: https://solutions.flywire.com/en/webhooks/notifications-v2
related_surfaces:
- ref: asyncapi/flywire-non-payment-webhooks.yml
  note: Separate invoice.* / payment_request.* event catalog on solutions.flywire.com.