Skip to main content

Order Failed

This event is triggered when a subscriber's payment attempt fails, either due to payment gateway rejection, insufficient funds, or other payment-related issues.

Event Type​

order.created.failed

Setting Up the Webhook​

To subscribe to this webhook event, configure your webhook endpoint with the following:

curl -X 'POST' \
  'https://api-prod-new.tagmango.com/api/v1/integration/webhook/webhook' \
  -H 'accept: application/json' \
  -H 'x-api-key: <Your API Key>' \
  -H 'Content-Type: application/json' \
  -d '{
  "hookUrl": "<your webhook url>",
  "event": "order.created.failed",
  "mango": "<mango to be associated> (optional sends all mango related events if not specified)"
}'

Parameters

ParameterTypeRequiredDescription
hookUrlstringYesYour webhook endpoint URL
eventstringYesMust be `order.created.failed`
mangostringNoSpecific mango ID to monitor. If not specified, receives events for all mangoes

Webhook Payload​

When a payment attempt fails, TagMango will send a POST request to your webhook URL with the following payload:

Example

{
  "subscriberId": "634fc35ddaf58580e2418c40",
  "name": "Subscriber Name",
  "email": "someone@example.com",
  "phone": 1234567890,
  "country": "IN",
  "dialCode": "+91",
  "orderId": "634fc35ddaf58580e2418c40",
  "orderTime": "2025-02-03T12:36:18.831Z",
  "amount": 100,
  "gst": 0,
  "discount": 20,
  "coupon": "CODE",
  "amountPayable": 90,
  "mangoName": "Your mango",
  "status": "completed",
  "recurringType": "monthly",
  "currency": "INR",
  "quantity": 1,
  "affiliateId": "634fc35ddaf58580e2418c40",
  "affiliateName": "Affiliate Name",
  "affiliateEmail": "affiliate@example.com",
  "affiliatePhone": 123467890,
  "customFields": null,
  "funnelBridgeDetails": null,
  "renewalCount": 3
}

Schema

subscriberId
string
The subscriber's unique identifier
name
string
The subscriber's full name
email
string
The subscriber's email address
phone
number
The subscriber's phone number
country
string
Country code of the subscriber
dialCode
string
Country dial code for the phone number
orderId
string
Unique identifier for the order
orderTime
string
Timestamp of when the order was place, in UTC
amount
number
Original amount before taxes and discounts
gst
number
GST/tax amount applied to the order
discount
number
Discount amount applied to the order
coupon
string
Coupon code applied to the order
amountPayable
number
Final amount paid by the subscriber after discounts and taxes
mangoName
string
Name of the mango which was purchased
status
string
Order status
recurringType
string
Type of recurring subscription
currency
string
Currency code for the transaction by the subscriber or customer
quantity
number
Quantity of items purchased
affiliateId
string | null
Affiliate identifier if order came through affiliate program, (will only be present if purchased through an affiliate link)
affiliateName
string | null
Name of the affiliate, (will only be present if purchased through an affiliate link)
affiliateEmail
string | null
Email address of the affiliate, (will only be present if purchased through an affiliate link)
affiliatePhone
number | null
Phone number of the affiliate, (will only be present if purchased through an affiliate link)
customFields
object | null
Any custom fields configured in your mango as key-value pairs, if not configured in mango, this will be null
Show 2 properties
funnelBridgeDetails
array | null
FunnelBridge details, (will only be present if purchased through a funnel bridged purchase link)
Show 3 properties
renewalCount
number | null
Number of times the subscription of the mango was renewed, (will only be present if the mango is recurring)
Failure Details

The payload includes details about the failed payment attempt. The status field will be set to failed.

Custom Fields

The payload may also include any custom fields configured in your mango as additional key-value pairs in the customFields object.

Handling the Webhook​

Your webhook endpoint should:

  1. Respond with 200 status - Return a 200 HTTP status code to acknowledge receipt
  2. Process quickly - Respond within 30 seconds to avoid timeouts
  3. Implement idempotency - Handle duplicate events gracefully
  4. Verify authenticity - Validate the request using the provided authentication headers

Example Implementation​

// Node.js Express example
app.post("/webhook", (req, res) => {
  const payload = req.body;

  // Verify the webhook authenticity (implement based on your security setup)
  if (!verifyWebhook(req)) {
    return res.status(401).send("Unauthorized");
  }

  // Process the webhook event
  try {
    console.log("Event data:", JSON.stringify(payload, null, 2));

    // Your business logic here
    // Process the event data according to your application needs
    processWebhookEvent(eventType, payload);
  } catch (error) {
    console.error("Error processing webhook:", error);
    // You might want to return 500 here depending on your retry policy
  }

  // Acknowledge receipt
  res.status(200).send("OK");
});

function processWebhookEvent(eventType, payload) {
  // Implement your custom logic based on the event type and payload
  // This is where you'll handle the webhook data according to your business requirements

  // Examples of what you might do:
  // - Store event data in your database
  // - Send notifications to users
  // - Update user records
  // - Trigger automated workflows
  // - Sync data with external systems

  console.log(`Processing ${eventType} event for your application`);
}