Q&A

Following our Upcoming Transaction Status Changes announcement, several partners reached out with questions. We've compiled those — and other related inquiries — here for everyone’s reference.

❓ Q: Will the transaction record attributes change in any other way?

The top-level structure and attributes of the transaction object will remain unchanged. The status field will reflect the new values outlined in the changelog. Additionally, depending on the action, new attributes may appear under references. The examples below are not exhaustive and may expand over time.

references.

• authorization_id
• capture_id

❓ Q: How long will the temporary APPROVED webhook be in place (for CHARGE and PAYOUT)?

The transitional APPROVED status will remain available for 90 days post-deployment — approximately until the end of September 2025.

❓ Q: What will the temporary webhook payload look like?

The webhook payload structure will remain unchanged. The only differences will be in the values — specifically in the status and possibly in the references section.

❓ Q: What statuses will now be broadcast for both the transactions:create and transactions:update webhook events?

transactions:create will give you the initially created transaction, before processing has begun. So the status value will be PROCESSING.

transactions:update the vast majority of the statuses will be sent via this event: AUTHORIZING, AUTHORIZED, CAPTURING, CAPTURED, SETTLED, FUNDED, CHARGING, CHARGED, PAYING, PAIDOUT, VOIDING, VOIDED, REFUNDING, REFUNDED, NOT AUTHORIZED, DECLINED, FAILED, ERROR

Note: As additional transaction lifecycle events are added, this will result in additional statuses appropriate to that action and the underlying payment method (tender).

❓ Q: How do I update my webhook subscriptions to only receive the events I care about?

You should create multiple webhook subscriptions — even for the same destination — and use conditions to filter based on action and status.

Example: to receive events only when the status is APPROVED for CHARGE transactions:

{
  "destination": "https://your.destination/goes/here",
  "type": "transactions.update",
  "conditions": {
    "action": "CHARGE",
    "status": "APPROVED"
  }
}

To also receive DECLINED for CHARGE, add a second subscription:

{
  "destination": "https:\/\/your.destination\/goes\/here",
  "type": "transactions.update",
  "conditions": {
    "action": "CHARGE",
    "status": "DECLINED"
  }
}

Note: As of now, the v3.3 documentation does not list transactions as an event type — this will be updated alongside the upcoming transaction changes.

❓ Q: How do I know when a transaction is “done” for a given action?

"Done" can vary by action. Here's a breakdown of common final or terminal statuses:

❓ Q: How do I get more lifecycle detail for specific gateways?

While lifecycle support (e.g., SETTLED, FUNDED) has been added, not all providers support it yet. If you need enhanced lifecycle tracking for a specific gateway, contact us at [email protected], and we’ll prioritize configuration updates accordingly.

Examples

Webhook Subscription Behavior

🟡 Note:
The status PROCESSING will only be returned via the create:transaction webhook.
All other statuses discussed below (e.g., AUTHORIZED, CAPTURED, VOIDED, etc.) are returned via the update:transaction webhook.

Transaction - Charge

Applies to customers using our “create transaction” endpoint with the action of CHARGE, or creating a business process with a CHARGE action.

Today,: Authvia processes an authorization and capture in one CHARGE API call. These are the statuses: APPROVED, DECLINED, ERROR, FAILED, VOIDED, PAYMENT-IN-PROGRESS, NOT AUTHORIZED

Post release: Authvia will continue to process an authorization and capture in one API call, when the action is CHARGE. The transaction will flow through the following statuses:

The following statuses exist for both provider types: DECLINED, ERROR, FAILED, NOT AUTHORIZED, PAYMENT-IN-PROGRESS

Post-release + Enhanced Provider Mapping: Soon after this release, provider mapping files may be updated, and additional final statuses may also appear: SETTLED, FUNDED

Transaction – Separate Authorization & Capture

Post-release + Enhanced Provider Mapping: After the webhook status changes, provider mapping files will be updated to allow Authvia customers to process separate authorizations and captures.

When a customer initiates separate Authorize and Capture actions, the transaction will reflect a more granular status flow:

Transaction - Reversal

Applies to customers using our “create transaction” endpoint with the action of REVERSAL.

Transaction - Payout

Applies to customers using our “create transaction” endpoint with the action of PAYOUT or creating a business process with a PAYOUT action.