Overview

This guide helps you understand which webhooks you need to consume if you are using payment methods that return immediate authorization responses, thus ensuring a smoother, more transparent integration.

Prerequisites

• Familiarity with Recurly Webhooks
• Basic understanding of RESTful APIs and JSON
• Access to Recurly with valid API credentials

Definition

In the context of webhooks, a synchronous payment method is one where the final status of the transaction (success, declined, or error) is returned immediately in the direct API response to the payment request. While a webhook event (like payment.succeeded) might still be sent afterward for backend reconciliation or to trigger fulfillment, your checkout system does not need to wait for this webhook to confirm the payment's outcome to the consumer.

Supported Payment Methods

• Credit Cards and Wallets using Credit Cards including: Apple Pay, Google Pay, Cash App, Amazon Pay, Link Pay (Cards only), Venmo, PayPal, and Klarna.
• Instant Payment Methods: iDeal, Klarna Debit Risk (aka Sofort)

Suggested Events

Please note, this list is not exhaustive, please review the entire list of events as there may be others that serve your specific use case. This list serves as the bare minimum for a successful implementation.

Payment Notifications

Specific to Payments notifications, you will want to listen for the following events. See the events list for all Payments event notifications and their descriptions.

• payment.succeeded : Sent when a Purchase payment is successfully approved immediately. This will also apply to status updates for Asynchronous methods.
• payment.failed: Sent when a payment fails or is declined immediately. This will also apply to status updates to Asynchronous methods.
• payment.authorized: Sent when using separate Auth and Capture, when the Authorization is successfully approved.

Invoice Notifications

Invoices for synchronous payment methods will immediately move to a Paid or Past Due state in most cases. They are also automatically created on all transactions except for verifications. You can read about all events on the dedicated Invoice notifications documentation.

• invoice.created : Sent when a new invoice is generated. This will also apply to Asynchronous methods. As with all webhooks, you'll want to query on the relevant invoice id to see the status of the payment.

Subscription Notifications

Subscription notifications are sent when an action is taken against a specific subscription within an account. Read more about subscription-level notifications in our dedicated documentation.

• subscription.created : Sent when a new Subscription is created for a customer. This will also apply to Asynchronous methods.
• subscription.renewed: Sent when an active subscription's renewal invoice is paid successfully. This will also apply to Asynchronous methods.
• subscription.canceled: Sent when subscription is canceled, and will not renew, but is valid until its next bill date. This will also apply to Asynchronous methods.
• subscription.expired: Sent when a subscription is expired, rendering it invalid immediately. This state also applies to Asynchronous payment methods.