Webhooks (Notifications)

• Background
• Configuring the Notification URL
• Base Notification Structure
• Subscription and Payment Status
• Requets Authentication
• Subscription Events

Background

This API provides real-time notifications to merchants about changes in customer subscriptions. It uses web hooks to send JSON payloads to the merchant's specified notification URL.

Configuring the Notification URL

To receive subscription notifications, you must provide a notification_url when creating a new subscription using the /api/v1.3/subscription endpoint (or via the Atlas back-office). This URL should be a valid HTTPS endpoint on your server that can accept and process the notification payloads.

Example:

{
    // ... (other subscription parameters)
    "notification_url": "https://your-website.com/subscriptions/webhook-handler"
}

Base Notification Structure

Each notification request includes both static parameters and dynamic event_data:

{
    "event": "EVENT_NAME", 
    "merchant_id": "API-Merchant",
    "application_key": "test-application",
    "cid": "user-1234",
    "plan_id": "i2VANeFxKR1aZGoH",
    "subscription_id": "1GQ0xJonekLvqKTUdH1ELyYs",
    "subscription_status": "inactive",
    "event_data": {...},
    "version": 1.3,
    "timestamp": 1680712861
}

• event: The type of subscription event (e.g., SubscriptionCreated, PaymentFailed).
• merchant_id: The API account of the merchant
• application_key: Identifier of your application (website) with praxis.
• cid: Customer identifier.
• plan_id, subscription_id: Subscription details.
• subscription_status: Current status of the subscription, refer to Subscription and Payment Status.
• event_data: Specific data related to the event.
• version: API version.
• timestamp: UNIX timestamp of the event.

Subscription and Payment Status

This section details the possible values for subscription statuses and payment statuses, along with explanations of their meanings.

Subscription Status

Subscription status is sent as part of the base notification structure, i.e. for all Subscription Events

Status	Description	Payment Statuses (if applicable)
active	The subscription is active, and the user has access to services.	trial_period, payment_successful, manual_payment
inactive	The subscription is inactive due to payment issues, manual deactivation, or creation without activation.	retry_failed, card_token_expired, or null (if no payment has been attempted)
expired	The subscription has reached the maximum number of billing cycles specified in its settings.
canceled	The subscription has been canceled via the Atlas interface or the API.

Payment Status

Payment status is received as part of the event_data of subscription events, please see the section below Subscription Events

Status	Description	Associated Subscription Status
trial_period	The subscription is in its trial period and no payment has been made yet.	active
payment_successful	The payment for the billing cycle has been processed successfully.	active
payment_failed	The payment attempt failed, and retry options are still available.	inactive
retry_failed	All payment retry attempts have been exhausted.	inactive
manual_payment	The payment was processed manually outside of the Subscription service.	active
card_token_expired	The payment failed because the card token associated with the subscription has expired.	inactive

Request Authentication

To ensure the security and integrity of notifications, each request is signed using a signature generation algorithm. This signature is based on the following parameters:

• event
• merchant_id
• application_key
• cid
• plan_id
• subscription_id
• subscription_status
• timestamp

The full signature generation algorithm can be found in the Authentication section of the Praxis documentation: Authentication

Verification on Your Server

Your webhook handler should verify the signature in each incoming notification request. If the signature is invalid, the request should be rejected. This helps prevent unauthorized or tampered-with notifications.

Subscription Events

SubscriptionCreated

Purpose: Notifies the merchant that a new subscription has been successfully initiated.

Use Cases:

• Trigger welcome emails or onboarding processes for new subscribers.
• Update internal systems to reflect the new subscription.
• Initiate any immediate actions based on the subscription plan (e.g., granting access to premium features), in case the event is received with subscription_status: "active"

Event Data Parameters:

• card_token: The unique identifier for the customer's payment card.
• amount: The subscription amount in minor units (e.g., cents).
• currency: The currency code (e.g., "USD", "EUR").
• created_at: The timestamp when the subscription was created (UNIX format).
• expired_at: The timestamp when the subscription will expire (UNIX format).

Request Example:

"event_data": {
    "card_token": "a52028efb6ccbedd65c066ce284c7dfb",
    "amount": 20000,
    "currency": "EUR",
    "created_at": 1680712861,
    "expired_at": 1680821826
}

SubscriptionActivated

Purpose: Signals that a previously inactive or disabled subscription has been reactivated.

Use Cases:

• Restore access to services or content for the subscriber.
• Notify the customer that their subscription is active again.
• Update internal records to reflect the change in status.

Event Data Parameters:

• payment_status: The current payment status of the subscription (e.g., "trial", "active", "past_due").
• previous_subscription_status: The status the subscription was in before activation (e.g., "inactive", "disabled").
• next_payment_date: The timestamp of the next scheduled payment.

Request Example:

"event_data": {
    "payment_status": "trial",
    "previous_subscription_status": "inactive",
    "next_payment_date": 1680832726
}

SubscriptionDeactivated

Purpose: Informs the merchant that a subscription has been temporarily paused.

Use Cases:

• Temporarily suspend access to services or content.
• Investigate the reason for deactivation (e.g., failed payment, manual pause).
• Notify the customer about the pause and any potential actions they need to take.

Event Data Parameters:

• payment_status: The current payment status of the subscription (e.g., "retry_failed", "paused").
• previous_subscription_status: The status the subscription was in before deactivation.
• deactivation_reason: The reason for deactivation (manual, fraud, retry_payment_failed, card_token_expired).
• inactive_lifetime: Number of days the subscription can remain inactive before being canceled (if applicable).
• cancel_date: The date the subscription will be canceled if no action is taken (if applicable).

Request Example:

"event_data": {
    "payment_status": "retry_failed",
    "previous_subscription_status": "active",
    "deactivation_reason": "manual",
    "inactive_lifetime": 14,
    "cancel_date": 1680821726
}

SubscriptionExpired

Purpose: Indicates that a subscription has reached its natural end date.

Use Cases:

• Revoke access to premium features or content.
• Send renewal reminders or offers to the customer.
• Archive the subscription data for historical reference.

Event Data Parameters:

• billing_cycles_number: The total number of billing cycles completed for the subscription.
• expired_date: The timestamp when the subscription expired.

Request Example:

"event_data": {
    "billing_cycles_number": 12,
    "expired_date": 1680821726
}

SubscriptionCanceled

Purpose: Communicates that a subscription has been terminated.

Use Cases:

• Permanently revoke access to services or content.
• Analyze the cancellation reasons for churn prevention.
• Send cancellation confirmation emails to the customer.

Event Data Parameters:

• payment_status: The current payment status of the subscription (e.g., "canceled").
• previous_subscription_status: The status the subscription was in before cancellation.
• cancellation_reason: The reason for cancellation (manual, retry_payment_failed, inactive_lifetime_expired, reject_reason).

Request Example:

"event_data": {
    "payment_status": "retry_failed",
    "previous_subscription_status": "active",
    "cancelation_reason": "manual" 
}

PaymentAttemptApproved, PaymentAttemptFailed

Purpose: Provide granular insights into individual payment attempts, whether successful or not.

Use Cases:

• Track payment success rates and identify potential issues.
• Log detailed transaction information for reconciliation.
• Implement custom retry logic based on the number of failed attempts.

Event Data Parameters:

• attempt_number: The sequential number of this payment attempt.
• transaction_status: Status of the attempt ("approved", "rejected", "error").
• tid: Trace ID.
• transaction_id: Transaction ID from the payment gateway.
• order_id: Order ID associated with the payment.
• currency: Currency code (e.g., EUR, USD).
• amount: Payment amount in minor units (e.g., cents).
• payment_method: Payment method used.
• payment_processor: Name of the payment processor.
• gateway: Gateway Hash.
• card: Card detail object.
• status_code: status code from payment gateway.
• status_details: description from the payment gateway.

Request Example:

{
    "attempt_number": 1,
    "transaction_status": "approved",
    "tid": 756850,
    "transaction_id": "13348",
    "order_id": "1GQ0xJonekLvqKTUdH1ELyYs-2023-04-12-1",
    "currency": "EUR",
    "amount": 100,
    "payment_method": "Credit Card",
    "payment_processor": "TestCardProcessor",
    "gateway": "a6966c795cc4b6cbdfe5c1d49ce918b7",
    "card": {
        "card_token": "J-4-a0vPhjZ9R75JP98VDUFgbh9y8sYr",
        "card_type": "VISA",
        "card_number": "411111******1111",
        "card_exp": "12\/2024",
        "card_issuer_name": "Bank of Somewhere",
        "card_issuer_country": "GB"
    },
    "status_code": "SC-002",
    "status_details": "Transaction approved"
}

PaymentFailed, PaymentSucceeded

Purpose: Triggered when the overall payment process is finalized (failed or successful), indicating the total attempts made.

Use Cases:

• Update the subscription status (e.g., mark as overdue if payment failed).
• Trigger dunning or retry mechanisms for failed payments.
• Send payment confirmation emails to customers.

Event Data Parameters:

• total_attempts_number: Total number of payment attempts made for this billing cycle.

Request Example:

"event_data": {
    "total_attempts_number": 3 
}

PaymentManuallyPaid

Purpose: Notifies the merchant of a successful offline or out of bounds payment for a subscription.

Use Cases:

• Update the subscription status to reflect the payment.
• Reconcile offline payments with internal accounting systems.
• Send payment confirmation emails to customers.

Event Data Parameters:

• subscription_id: Subscription identifier.
• billing_cycle_date: The billing cycle date the payment corresponds to.
• order_id: The order ID associated with the payment.
• currency: The currency of the payment.
• amount: The payment amount.
• status_code: A code representing the payment status.
• status_details: More information about the payment status.

Request Example:

"event_data": {
    "subscription_id": "1GQ0xJonekLvqKTUdH1ELyYs",
    "billing_cycle_date": "2023-04-12",
    "order_id": "1GQ0xJonekLvqKTUdH1ELyYs-2023-04-12-4",
    "currency": "EUR",
    "amount": 100,
    "status_code": "SC-002",
    "status_details": "Transaction approved"
}