asyncapi: 2.6.0 info: title: Affirm Webhooks description: >- Affirm uses webhooks to notify merchant endpoints in real time when events occur during the customer checkout and prequalification flows. Webhooks are available to Key and Enterprise merchants. Affirm sends two types of webhooks: checkout events delivered as application/x-www-form-urlencoded and prequalification events delivered as application/json. Checkout events fire as customers move through the Affirm financing flow, including opened, approved, not_approved, and confirmed status transitions. Prequalification events fire during the Affirm prequal flow, indicating approval decisions and expiry. Each webhook request includes an X-Affirm-Signature header containing a Base64-encoded HMAC signature that merchants can use to verify the request originated from Affirm. Merchant webhook endpoints must support TLS 1.2 and respond with a 2xx status code to acknowledge receipt. Affirm does not retry failed webhook deliveries. version: '1.0' contact: name: Affirm Developer Support url: https://docs.affirm.com/developers/docs/development-quickstart servers: merchantWebhookEndpoint: url: '{webhookUrl}' protocol: https description: >- The merchant-configured HTTPS endpoint that receives webhook event notifications from Affirm. Must support TLS 1.2 and respond with a 2xx HTTP status to acknowledge receipt. variables: webhookUrl: description: >- The merchant's configured webhook endpoint URL, set up via the Affirm Merchant Portal or through the merchant's Technical Account Manager. security: - affirm_signature: [] channels: /webhooks/checkout: description: >- Channel for Affirm checkout lifecycle events. Affirm sends POST requests with content-type application/x-www-form-urlencoded to the merchant's configured webhook endpoint as customers progress through the checkout flow. publish: operationId: receiveCheckoutEvent summary: Receive a checkout event description: >- A checkout event fired by Affirm when the customer's checkout status changes. Covers the full lifecycle from checkout initiation through approval and customer confirmation. The event payload is delivered as URL-encoded form data and includes customer PII, loan terms, and order details as configured in the merchant's Data Sharing Agreement. message: oneOf: - $ref: '#/components/messages/CheckoutOpenedEvent' - $ref: '#/components/messages/CheckoutApprovedEvent' - $ref: '#/components/messages/CheckoutNotApprovedEvent' - $ref: '#/components/messages/CheckoutConfirmedEvent' /webhooks/prequal: description: >- Channel for Affirm prequalification events. Affirm sends POST requests with content-type application/json to the merchant's configured webhook endpoint as customers complete or expire from the prequalification flow. publish: operationId: receivePrequalEvent summary: Receive a prequalification event description: >- A prequalification event fired by Affirm when a customer completes or expires from the Affirm prequalification flow. Events include an approval decision with loan terms and a prequalification expiry notification. message: oneOf: - $ref: '#/components/messages/PrequalDecisionEvent' - $ref: '#/components/messages/PrequalExpiryEvent' components: securitySchemes: affirm_signature: type: httpApiKey in: header name: X-Affirm-Signature description: >- Base64-encoded HMAC signature included in every webhook request from Affirm. Merchants can verify this signature to confirm the request originated from Affirm rather than a third party. The signature is computed using the merchant's private API key as the HMAC secret. messages: CheckoutOpenedEvent: name: CheckoutOpenedEvent title: Checkout Opened summary: Fired when a customer opens the Affirm checkout flow. description: >- Affirm fires this event when a customer initiates the Affirm checkout flow and is presented with the login screen. This is the first event in the checkout webhook lifecycle. contentType: application/x-www-form-urlencoded headers: type: object properties: X-Affirm-Signature: type: string description: Base64-encoded HMAC signature for request verification. User-Agent: type: string description: Always set to "Affirm-Webhook" for Affirm webhook requests. example: Affirm-Webhook payload: $ref: '#/components/schemas/CheckoutEventPayload' CheckoutApprovedEvent: name: CheckoutApprovedEvent title: Checkout Approved summary: Fired when a customer receives a positive credit decision from Affirm. description: >- Affirm fires this event when the customer's credit application is approved and financing terms are offered. The payload includes the approved loan amount, APR, payment terms, and customer information as configured in the Data Sharing Agreement. contentType: application/x-www-form-urlencoded headers: type: object properties: X-Affirm-Signature: type: string description: Base64-encoded HMAC signature for request verification. User-Agent: type: string example: Affirm-Webhook payload: $ref: '#/components/schemas/CheckoutApprovedPayload' CheckoutNotApprovedEvent: name: CheckoutNotApprovedEvent title: Checkout Not Approved summary: Fired when a customer receives a negative credit decision from Affirm. description: >- Affirm fires this event when the customer's credit application is not approved and financing cannot be offered for the requested amount. The merchant can use this event to present alternative payment options to the customer. contentType: application/x-www-form-urlencoded headers: type: object properties: X-Affirm-Signature: type: string description: Base64-encoded HMAC signature for request verification. User-Agent: type: string example: Affirm-Webhook payload: $ref: '#/components/schemas/CheckoutEventPayload' CheckoutConfirmedEvent: name: CheckoutConfirmedEvent title: Checkout Confirmed summary: Fired when a customer confirms their financing and is redirected back to the merchant. description: >- Affirm fires this event when the customer clicks confirm at the end of the Affirm checkout flow and is redirected back to the merchant's user_confirmation_url. This is the final checkout event and indicates the customer has accepted the loan terms. The checkout token can now be exchanged server-side for a transaction authorization. contentType: application/x-www-form-urlencoded headers: type: object properties: X-Affirm-Signature: type: string description: Base64-encoded HMAC signature for request verification. User-Agent: type: string example: Affirm-Webhook payload: $ref: '#/components/schemas/CheckoutConfirmedPayload' PrequalDecisionEvent: name: PrequalDecisionEvent title: Prequalification Decision summary: Fired when a customer receives an approval decision during prequalification. description: >- Affirm fires this event when a customer completes the prequalification flow and receives a financing decision. The payload includes approved amount, APR, remaining credit, and customer information as configured in the merchant's Data Sharing Agreement. contentType: application/json headers: type: object properties: X-Affirm-Signature: type: string description: Base64-encoded HMAC signature for request verification. User-Agent: type: string example: Affirm-Webhook payload: $ref: '#/components/schemas/PrequalEventPayload' PrequalExpiryEvent: name: PrequalExpiryEvent title: Prequalification Expiry summary: Fired when a customer's prequalification expires. description: >- Affirm fires this event when a prequalification offer expires. This can occur within the prequalification session or up to 7 days after the prequalification was completed. Merchants can use this event to prompt customers to re-qualify. contentType: application/json headers: type: object properties: X-Affirm-Signature: type: string description: Base64-encoded HMAC signature for request verification. User-Agent: type: string example: Affirm-Webhook payload: $ref: '#/components/schemas/PrequalEventPayload' schemas: CheckoutEventPayload: type: object description: >- Base payload for Affirm checkout webhook events, delivered as URL-encoded form data. Field availability depends on the merchant's Data Sharing Agreement configuration. properties: checkout_status: type: string description: The current status of the checkout that triggered this event. enum: - opened - approved - not_approved - confirmed order_id: type: string description: The merchant's order identifier associated with this checkout. total: type: integer description: Total checkout amount in cents. first_name: type: string description: Customer's first name (included per Data Sharing Agreement). last_name: type: string description: Customer's last name (included per Data Sharing Agreement). email: type: string description: Customer's email address (included per Data Sharing Agreement). CheckoutApprovedPayload: type: object description: >- Payload for the checkout approved event including loan terms and customer financing details. properties: checkout_status: type: string description: Set to "approved" for this event type. enum: - approved order_id: type: string description: The merchant's order identifier. total: type: integer description: Total checkout amount in cents. first_name: type: string description: Customer's first name. last_name: type: string description: Customer's last name. email: type: string description: Customer's email address. approved_amount: type: integer description: Total loan amount approved by Affirm in cents. amount_financed: type: integer description: Amount being financed by Affirm in cents. down_payment_amount: type: integer description: Down payment amount in cents, if applicable. has_down_payment: type: boolean description: Indicates whether a down payment is required for this loan. apr: type: number description: Annual percentage rate for the approved financing. number_of_payments: type: integer description: Total number of scheduled payments. installment_amount: type: integer description: Amount of each installment payment in cents. finance_charge: type: integer description: Total finance charge (interest) in cents. first_payment_date: type: string format: date description: Date of the first scheduled payment. expiration_date: type: string format: date-time description: Date and time when the approved loan offer expires. CheckoutConfirmedPayload: type: object description: >- Payload for the checkout confirmed event, including the checkout token to be exchanged for a transaction authorization. properties: checkout_status: type: string description: Set to "confirmed" for this event type. enum: - confirmed checkout_token: type: string description: >- The one-time checkout token to be exchanged server-side for a transaction authorization via the Transactions API. order_id: type: string description: The merchant's order identifier. total: type: integer description: Total checkout amount in cents. first_name: type: string description: Customer's first name. last_name: type: string description: Customer's last name. email: type: string description: Customer's email address. PrequalEventPayload: type: object description: >- Payload for Affirm prequalification webhook events, delivered as JSON. Field availability depends on the merchant's Data Sharing Agreement. properties: event_type: type: string description: Type of prequalification event. enum: - prequal_decision - prequal_expiry first_name: type: string description: Customer's first name. last_name: type: string description: Customer's last name. email: type: string description: Customer's email address. approved_amount: type: integer description: Approved prequalification amount in cents. remaining_credit_amount: type: integer description: Remaining available credit in cents after this prequalification. apr: type: number description: Annual percentage rate associated with the prequalification decision. prequal_terms: type: string description: Summary of the prequalification loan terms offered to the customer. expiration_date: type: string format: date-time description: Date and time when this prequalification offer expires.