--- updatedAt: 2026-05-28T07:31:57.000Z agentTools: projectIndex: https://docs.praxis.tech/llms.txt --- # Subscription Notification Notification from Praxis where merchant would receive subscription notifications when provided a [`notification_url`]() while creating new a new subscription using the /api/v1.3/subscription endpoint (or via the Atlas Back Office). # OpenAPI definition ```json { "openapi": "3.0.2", "info": { "title": "Webhooks", "version": "1.3", "description": "Praxis webhook APIs OAS 3.0.2 specification document" }, "servers": [ { "url": "https://{merchant_server}", "description": "Merchant's Server URL", "variables": { "merchant_server": { "default": "api.yourdomain.com", "description": "The base URL where your server receives webhooks" } } } ], "paths": { "/api/subscriptions": { "summary": "This specification provides the details for webhooks - subscriptions", "description": "Notification from Praxis where merchant would receive subscription notifications when provided a [`notification_url`]() while creating new a new subscription using the /api/v1.3/subscription endpoint (or via the Atlas Back Office).", "post": { "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/payload_webhook_subscription_requestData" }, "examples": { "subscription notification": { "value": { "event": "SubscriptionCreated", "merchant_id": "API-Merchant", "application_key": "test-application", "cid": "user-1234", "plan_id": "i2VANeFxKR1aZGoH", "subscription_id": "1GQ0xJonekLvqKTUdH1ELyYs", "subscription_status": "inactive", "event_data": { "amount": 11, "currency": "22", "created_at": 1680712861, "expired_at": 1680821826 }, "version": 1.3, "timestamp": 1680712861 } } } } }, "required": true }, "tags": [ "Webhooks" ], "parameters": [ { "name": "gt-authentication", "schema": { "$ref": "#/components/schemas/property_req_header_signature_params_for_webhook_subscription" }, "in": "header", "required": true } ], "responses": { "200": { "$ref": "#/components/responses/200-ok-webhook-notification-response-data" } }, "operationId": "subscriptionNotification", "summary": "Subscription Notification" } } }, "components": { "schemas": { "payload_webhook_notification_requestData": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/payload_webhook_customer_sync_requestData/allOf/1" }, { "required": [ "customer", "session" ], "type": "object", "properties": { "conversion_rate": { "description": "Conversion rate between `currency` and `processed_currency` applied during conversion from `amount` to `processed_amount`. Applies to successful transactions. The value is calculated as 1 processed_currency / 1 currency = conversion_rate", "maxLength": 30, "format": "double", "type": "number", "minimum": 0, "maximum": 9999999999.999998 }, "customer": { "$ref": "#/components/responses/200-ok-webhook-customer-sync-response-data/content/application~1json/schema/allOf/1/properties/customer_data", "title": "Customer" }, "session": { "$ref": "#/components/schemas/payload_webhook_validation_requestData/allOf/1/properties/session", "title": "Session" }, "transaction": { "title": "Transaction", "description": "Transaction object provided during the response.", "required": [ "transaction_status", "tid", "fee", "amount", "currency", "fee_included", "payment_method", "payment_processor", "gateway", "created_by", "edited_by", "status_code", "status_details", "transaction_type" ], "type": "object", "properties": { "transaction_type": { "description": "Transaction type. Allowed values are:\r\n- authorization (authorization and capture)\r\n- sale (deposit)\r\n- payout (withdrawal)\r\n- refund (return deposit funds)", "enum": [ "authorization", "sale", "payout", "refund" ], "maxLength": 16, "type": "string" }, "transaction_status": { "description": "Transaction status will change along with processing. Refer [Transaction Statuses](https://docs.praxis.tech/docs/transaction-statuses) for more details", "maxLength": 16, "type": "string" }, "tid": { "description": "Transaction identifier", "maxLength": 11, "type": "integer" }, "transaction_id": { "description": "PSP transaction identifier", "maxLength": 50, "type": "string" }, "currency": { "description": "**Base Currency**: The user's account currency on the merchant site.", "maxLength": 10, "type": "string" }, "amount": { "description": "Transaction amount in cents.\n\n*__Note__*: *For certain currencies there is a fraction other than 100 cents per unit, this is important if you multiply by 100 to send the amount in cents.*", "maxLength": 20, "type": "integer" }, "conversion_rate": { "$ref": "#/components/schemas/payload_webhook_notification_requestData/allOf/1/properties/conversion_rate" }, "processed_currency": { "description": "Actual currency processed. Applies to successful transactions. In Direct API processed_currency must match currency (transaction currency)", "maxLength": 3, "type": "string" }, "processed_amount": { "description": "Amount (in actual processing currency) in cents. Applies to successful transactions.", "maxLength": 20, "type": "integer" }, "spread_currency": { "description": "Actual currency processed. Applies to successful transactions. In Direct API processed_currency must match currency (transaction currency)", "maxLength": 3, "type": "string" }, "spread_amount": { "description": "The calculated amount that was subtracted from the total.", "maxLength": 20, "type": "integer" }, "fee": { "description": "Transaction fee based on the gateway settings", "maxLength": 20, "type": "integer" }, "fee_included": { "description": "Whether fee is included in the amount specified by customer within cashier or specified by the website in the cashier (VT) login call", "maxLength": 1, "enum": [ 0, 1 ], "type": "integer" }, "fee_type": { "description": "Can be either \"flat\" (flat fee amount) or \"percent\" (percent of the transaction amount) or \"hybrid\" ", "maxLength": 32, "type": "string", "enum": [ "flat", "percent", "hybrid" ] }, "payment_method": { "$ref": "#/components/schemas/payload_webhook_validation_requestData/allOf/1/properties/transaction_attempt/properties/payment_method", "description": "Payment method." }, "payment_processor": { "description": "Payment processor", "maxLength": 50, "type": "string" }, "gateway": { "description": "Gateway doing the processing.", "maxLength": 32, "type": "string" }, "card": { "description": "Tokenized card object", "type": "object", "properties": { "card_token": { "$ref": "#/components/schemas/payload_webhook_subscription_requestData/allOf/1/properties/event_data/oneOf/0/properties/card_token" }, "card_type": { "description": "Customer card type (AMEX, DinersClub, Discover, Electron, JCB, Maestro, MasterCard, Mir, VISA)", "maxLength": 10, "type": "string" }, "card_number": { "description": "Customer card number (4444 44** **** 1233)", "maxLength": 19, "type": "string" }, "card_exp": { "description": "Customer card exp (10/2023)", "maxLength": 8, "type": "string" }, "card_issuer_name": { "description": "Customer card issuing bank name", "maxLength": 255, "type": "string" }, "card_issuer_country": { "description": "Customer card issuing bank country", "maxLength": 2, "type": "string" }, "card_holder": { "description": "The cardholder name field will be sent to the CRM in the notification only if the setting in the Atlas BO is enabled. Otherwise, the key will not be sent at all (not 0 / null / empty string).", "maxLength": 255, "type": "string" }, "card_funding_source": { "description": "Funding source (DEBIT, CREDIT). This parameter including in the request by enabling an additional setting on Atlas BO.", "maxLength": 255, "type": "string" }, "card_subtype": { "description": "The card category subtype is CONSUMER or COMMERCIAL. This parameter is included in the request when an additional setting is enabled in the Atlas BO.", "maxLength": 255, "type": "string" } } }, "mit": { "description": "MIT object contains the list of settings for processing merchant-initiated transactions (MIT). The object is sent within notification only if MIT flow is used. ", "title": "mit", "required": [ "type" ], "type": "object", "properties": { "type": { "description": "Type of MIT transaction.\r\nPossible values:\r\n- initial\r\n- subsequent\r\n\r\n**Required** field for every MIT attempts", "maxLength": 32, "enum": [ "initial", "subsequent" ], "type": "string" }, "expiry": { "description": "Time to expire the transaction in days. After expiration, the system will not allow to process subsequent MIT using this transaction.\r\n\r\n**Optional**, default value is 365 (1 year).\r\n\r\n**Required** for '0-auth', 'mit-initial'", "maxLength": 5, "type": "integer" }, "mit_reference_id": { "description": "TID from previous successful zero-authorization or initial-mit transactions.\r\n**Required** for subsequent MIT requests.", "maxLength": 11, "type": "integer" } }, "example": { "type": "initial", "expiry": 365 } }, "wallet": { "description": "Tokenized wallet object", "type": "object" }, "is_async": { "description": "Credit card - indicates if the transaction processing involves the 3DSecure verification\r\n- 0 for synchronous flow (non-3D Secure)\r\n- 1 for asynchronous flow (3D Secure)", "maximum": 1, "enum": [ 0, 1 ], "type": "integer" }, "is_cascade": { "description": "Indicates the verification status of the cards returned in the list.\n- 1 for verified (default)\n- 0 for not verified", "maximum": 1, "enum": [ 0, 1 ], "type": "integer" }, "cascade_level": { "description": "Transaction retry number (in case of soft decline or network/application error during communication with PSP)", "maxLength": 2, "type": "integer" }, "reference_id": { "description": "In case of refund, this value specifies the ID of transaction to be refunded", "maxLength": 11, "type": "integer" }, "withdrawal_request_id": { "description": "Original transaction identifier from. Send the **tid** of withdrawal request if you want the payout amount to be deducted from withdrawal request as processed.", "maxLength": 11, "type": "integer" }, "account_identifier": { "description": "Account Identifier", "type": "string" }, "created_by": { "description": "Transaction initiator. Customer's activity is reflected with INTERNET, otherwise equals the name of the compliance or support agent", "maxLength": 50, "type": "string" }, "edited_by": { "description": "Transaction modified by. Customer's activity is reflected with INTERNET, otherwise equals the name of the compliance or support agent", "maxLength": 50, "type": "string" }, "status_code": { "description": "Processing status code (including processing and error codes)", "maxLength": 32, "type": "string" }, "status_details": { "description": "Verbal description of the processing status", "maxLength": 256, "type": "string" }, "promo_code": { "description": "Promo Code value, entered by the customer in Cashier.\r\n", "maxLength": 255, "type": "string" }, "redirect_url": { "description": "In order to have the \"redirect_url\" property appearing under transaction object, you will need to reach out to our support - requesting to enable the \"Notifications for the delayed processing via Direct API\" setting.\r\n\r\n_**Note:** Info that application may always include redirect_url attribute (empty or having the value) if requested from our support._", "maxLength": 256, "type": "string" } } } } } ] }, "payload_webhook_customer_sync_requestData": { "type": "object", "allOf": [ { "required": [ "cid" ], "type": "object", "properties": { "cid": { "description": "Unique customer id in your system.\r\n\r\n*__Note:__* *Personally Identifiable Information (PII), such as email addresses, is strictly forbidden. If your user identifier contains any PII, you must hash or encrypt it before sending it to the API.*", "maxLength": 50, "type": "string", "example": "1020" }, "order_id": { "description": "Transaction or session identifier in your system.", "maxLength": 50, "type": "string" } } }, { "required": [ "merchant_id", "application_key", "version", "timestamp" ], "type": "object", "properties": { "merchant_id": { "description": "Merchant API client account identifier.", "maxLength": 50, "type": "string", "example": "Sandbox-API" }, "application_key": { "description": "Identifier of your application (website).", "maxLength": 32, "type": "string", "example": "Sandbox-Application" }, "version": { "description": "API version.", "maxLength": 3, "type": "string", "example": "1.3" }, "timestamp": { "description": "Request time (unix timestamp, seconds).", "maxLength": 11, "type": "integer", "example": "1755853580" } } } ] }, "payload_webhook_subscription_requestData": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/payload_webhook_customer_sync_requestData/allOf/1" }, { "type": "object", "properties": { "event": { "description": "Defines the type of event being reported. Changes the schema of 'event_data'.", "enum": [ "SubscriptionCreated", "SubscriptionActivated", "SubscriptionDeactivated", "SubscriptionExpired", "SubscriptionCanceled", "PaymentAttemptApproved", "PaymentAttemptFailed", "PaymentSucceeded", "PaymentFailed", "PaymentManuallyPaid", "PaymentRefundSucceeded", "PaymentRefundFailed" ], "type": "string" }, "cid": { "$ref": "#/components/schemas/payload_webhook_customer_sync_requestData/allOf/0/properties/cid" }, "plan_id": { "description": "Subscription Plan ID", "maxLength": 32, "type": "string", "example": "i2VANeFxKR1aZGoH" }, "subscription_id": { "description": "Subscription ID", "maxLength": 32, "type": "string", "example": "tvoS9vGKdDwfGLLvp0r8JJ5d" }, "subscription_status": { "description": "Status of subscription. List of possible statuses:\r\n- Active - customer subscription in active status.\r\n- Inactive - customer subscription inactive.\r\n- Expired - customer subscription expired.\r\n- Canceled - customer subscription removed.", "maxLength": 8, "type": "string", "enum": [ "active", "inactive", "expired", "canceled" ] }, "event_data": { "oneOf": [ { "title": "EventData for SubscriptionCreated", "description": "Payload for the SubscriptionCreated event.", "type": "object", "properties": { "card_token": { "description": "HASH value of customer's card.\n\n*__Note:__* *This field must not be sent in any subsequent Merchant Initiated Transaction (MIT) requests.*", "maxLength": 32, "type": "string", "example": "af7d1b07c48fbeff116b2bb3e84fb4c9" }, "amount": { "$ref": "#/components/schemas/payload_webhook_notification_requestData/allOf/1/properties/transaction/properties/amount", "description": "The subscription amount in minor units (e.g., cents)." }, "currency": { "$ref": "#/components/schemas/payload_webhook_notification_requestData/allOf/1/properties/transaction/properties/currency" }, "created_at": { "description": "The timestamp when the subscription was created (UNIX format).", "type": "integer", "example": 1680712861 }, "expired_at": { "description": "The timestamp when the subscription will expire (UNIX format)", "type": "integer", "example": 1680821826 } } }, { "title": "EventData for SubscriptionActivated", "description": "Payload for the SubscriptionActivated event.", "type": "object", "properties": { "payment_status": { "description": "The current payment status of the subscription (e.g., `trial`, `active`, `past_due`)." }, "previous_subscription_status": { "description": "The status the subscription was in before activation (e.g., `inactive`, `disabled`)" }, "next_payment_date": { "description": "The timestamp of the next scheduled payment", "type": "integer" } } }, { "title": "EventData for SubscriptionDeactivated", "description": "Payload when a subscription is temporarily paused.", "type": "object", "properties": { "payment_status": { "description": "The current payment status of the subscription (e.g., `retry_failed`, `paused`).", "type": "string", "example": "retry_failed" }, "previous_subscription_status": { "description": "The status the subscription was in before deactivation.", "type": "string", "example": "active" }, "deactivation_reason": { "description": "The reason for deactivation (manual, fraud, retry_payment_failed, card_token_expired).", "type": "string", "example": "manual" }, "inactive_lifetime": { "description": "Number of days the subscription can remain inactive before being canceled (if applicable).", "type": "integer", "example": 14 }, "cancel_date": { "description": "The date (timestamp) the subscription will be canceled if no action is taken.", "type": "integer", "example": 1680821726 } } }, { "title": "EventData for SubscriptionExpired", "description": "Payload indicating a subscription has reached its natural end date.", "type": "object", "properties": { "billing_cycles_number": { "description": "The total number of billing cycles completed for the subscription.", "type": "integer", "example": 12 }, "expired_date": { "description": "The timestamp when the subscription expired.", "type": "integer", "example": 1680821726 } } }, { "title": "EventData for SubscriptionCanceled", "description": "Payload communicating that a subscription has been terminated.", "type": "object", "properties": { "payment_status": { "description": "The current payment status of the subscription (e.g., `canceled`, `retry_failed`).", "type": "string", "example": "retry_failed" }, "previous_subscription_status": { "description": "The status the subscription was in before cancellation.", "type": "string", "example": "active" }, "cancellation_reason": { "description": "The reason for cancellation (e.g., `manual`, `retry_payment_failed`, `inactive_lifetime_expired`).", "type": "string", "example": "manual" } } }, { "title": "EventData for PaymentAttemptApproved/Failed", "description": "Payload providing granular insights into individual payment attempts.", "type": "object", "properties": { "attempt_number": { "description": "The sequential number of this payment attempt.", "type": "integer", "example": 1 }, "transaction_status": { "description": "Status of the attempt (approved, rejected, error).", "type": "string", "example": "approved" }, "tid": { "description": "Trace ID for the payment attempt.", "type": "integer", "example": 756850 }, "transaction_id": { "description": "Transaction ID from the payment gateway.", "type": "string", "example": "13348" }, "order_id": { "description": "Order ID associated with the payment.", "type": "string", "example": "1GQ0xJonekLvqKTUdH1ELyYs-2023-04-12-1" }, "currency": { "description": "Currency code (e.g., EUR, USD).", "type": "string", "example": "EUR" }, "amount": { "description": "Payment amount in minor units.", "type": "integer", "example": 100 }, "payment_method": { "description": "Payment method used (e.g., Credit Card).", "type": "string", "example": "Credit Card" }, "payment_processor": { "description": "Name of the payment processor.", "type": "string", "example": "TestCardProcessor" }, "gateway": { "description": "Gateway Hash.", "type": "string", "example": "a6966c795cc4b6cbdfe5c1d49ce918b7" }, "card": { "title": "Card Detail", "description": "Detailed information about the card used for the transaction.", "type": "object", "properties": { "card_token": { "description": "Tokenized identifier for the card.", "type": "string", "example": "J-4-a0vPhjZ9R75JP98VDUFgbh9y8sYr" }, "card_type": { "description": "Card brand (e.g., VISA).", "type": "string", "example": "VISA" }, "card_number": { "description": "Masked card number.", "type": "string", "example": "411111******1111" }, "card_exp": { "description": "Card expiration date (MM/YYYY).", "type": "string", "example": "12/2024" }, "card_issuer_name": { "description": "Name of the card issuing bank.", "type": "string", "example": "Bank of Somewhere" }, "card_issuer_country": { "description": "ISO 3166-1 alpha-2 country code of the issuer.", "type": "string", "example": "GB" } } }, "status_code": { "description": "Status code from payment gateway.", "type": "string", "example": "SC-002" }, "status_details": { "description": "Description from the payment gateway.", "type": "string", "example": "Transaction approved" } } }, { "title": "EventData for PaymentFailed/Succeeded", "description": "Payload indicating the overall payment process is finalized for the billing cycle.", "type": "object", "properties": { "total_attempts_number": { "description": "Total number of payment attempts made for this billing cycle.", "type": "integer", "example": 3 } } }, { "title": "EventData for PaymentManuallyPaid", "description": "Payload for a successful offline or out-of-bounds payment for a subscription.", "type": "object", "properties": { "subscription_id": { "description": "Subscription identifier.", "type": "string", "example": "1GQ0xJonekLvqKTUdH1ELyYs" }, "billing_cycle_date": { "description": "The billing cycle date the payment corresponds to (YYYY-MM-DD).", "type": "string", "example": "2023-04-12" }, "order_id": { "description": "The order ID associated with the payment.", "type": "string", "example": "1GQ0xJonekLvqKTUdH1ELyYs-2023-04-12-4" }, "currency": { "description": "The currency of the payment.", "type": "string", "example": "EUR" }, "amount": { "description": "The payment amount in minor units.", "type": "integer", "example": 100 }, "status_code": { "description": "A code representing the payment status.", "type": "string", "example": "SC-002" }, "status_details": { "description": "More information about the payment status.", "type": "string", "example": "Transaction approved" } } }, { "title": "EventData for PaymentRefundSucceeded/Failed", "description": "Payload providing information about the refund attempt initiated by the Subscription Service.", "type": "object", "properties": { "reference_id": { "description": "The ID of the original sale transaction.", "type": "integer", "example": 756061 }, "transaction_status": { "description": "Status of the refund transaction (approved, rejected, error).", "type": "string", "example": "approved" }, "tid": { "description": "Trace ID.", "type": "integer", "example": 756850 }, "transaction_id": { "description": "Transaction ID from the payment gateway.", "type": "string", "example": "13348" }, "order_id": { "description": "The order ID associated with the payment.", "type": "string", "example": "1GQ0xJonekLvqKTUdH1ELyYs-2023-04-12-1" }, "currency": { "description": "Currency code (e.g., EUR, USD).", "type": "string", "example": "EUR" }, "amount": { "description": "Payment amount in minor units.", "type": "integer", "example": 25000 }, "payment_method": { "description": "Payment method used.", "type": "string", "example": "Credit Card" }, "payment_processor": { "description": "Name of the payment processor.", "type": "string", "example": "Test Card Processor" }, "gateway": { "description": "Gateway Hash.", "type": "string", "example": "a6966c795cc4b6cbdfe5c1d49ce918b7" }, "card": { "$ref": "#/components/schemas/payload_webhook_subscription_requestData/allOf/1/properties/event_data/oneOf/5/properties/card" }, "status_code": { "description": "Status code from payment gateway.", "type": "string", "example": "SC-002" }, "status_details": { "description": "Description from the payment gateway.", "type": "string", "example": "Transaction approved" } } } ], "description": "Data payload specific to the 'event' type." } } } ] }, "property_req_header_signature_params_for_webhook_subscription": { "title": "signature", "description": "Authentication HTTP header of an incoming webhook subscription request from Praxis.\nVerify the signature with the below attributes from the webhook customer sync request.\n- `event`\n- `merchant_id` \n- `application_key`\n- `cid`\n- `plan_id`\n- `subscription_id` \n- `subscription_status`\n- `timestamp`", "type": "string", "example": "15ca3dadf8e1cb8a64301317f3ce5f8587d1adf37e42ae50702ae35732974193f3f464ddcb019fa0e2f5f3043b1cd23b" } }, "responses": { "200-ok-webhook-notification-response-data": { "headers": { "external-request-signature": { "schema": { "title": "signature", "description": "Authentication HTTP header of the incoming response from the API.\nBelow response parameters should be used for validating the signature in response header.\n- `status`\n- `timestamp`", "type": "string", "example": "15ca3dadf8e1cb8a64301317f3ce5f8587d1adf37e42ae50702ae35732974193f3f464ddcb019fa0e2f5f3043b1cd23b" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/responses/409-conflict-webhook-notification-response-data/content/application~1json/schema" }, "examples": { "notification - success response": { "value": { "description": "Ok", "status": 0, "version": "1.3", "timestamp": 1590611635 } }, "notification - duplicate/handled response": { "value": { "status": 1, "description": "Transaction already updated manually at the website to final status", "version": "1.3", "timestamp": 1590611635 } } } } }, "description": "OK - Successful response" }, "409-conflict-webhook-notification-response-data": { "content": { "application/json": { "schema": { "required": [ "status", "description", "version", "timestamp" ], "type": "object", "properties": { "status": { "description": "API communication status - for transaction processing status please refer to `transaction.transaction.status`\r\n- 0 if the request was successful.\r\n- Negative integer if internal server/network error occurs.\r\n- Positive integer if application/logical error occurs. Refer [API Status & Error Codes](https://docs.praxis.tech/docs/api-status-and-error-codes) for more information.", "type": "integer" }, "description": { "description": "Accurate description of the result. Return the actual error for any exception as it helps to diagnose issues in production.\r\n", "type": "string", "maxLength": 256 }, "version": { "$ref": "#/components/schemas/payload_webhook_customer_sync_requestData/allOf/1/properties/version" }, "timestamp": { "$ref": "#/components/schemas/payload_webhook_customer_sync_requestData/allOf/1/properties/timestamp" } } }, "examples": { "notification - duplicate response": { "value": { "status": 1, "description": "Transaction already updated manually at the website to final status", "version": "1.3", "timestamp": 1590611635 } } } } }, "description": "Conflict - Duplicate response" } } } } ```