Subscription Object

This webhook is triggered when a subscription is renewed.

You can expect the below object when you register a webhook for the following events:

subscription.succeeded
subscription.failed

Integration model

Keep these constraints in mind when designing an API integration around subscriptions:

You can attach an existing subscription to a payment link. Create Payment Link accepts a subscription_id parameter. Pass the identifier of a subscription you created with Create Subscription, and the API re-parents that subscription onto the newly created link, so its billing continues against the new link. (If you pass a subscription object instead of a subscription_id, the API creates a brand-new subscription attached to the link.)
How enrollment works depends on which parameter you send. A link carrying a subscription object creates a new subscription; a link carrying a subscription_id moves that existing subscription onto the link rather than creating another one. There is no "join an existing subscriber" flow from the link.
external_id is a top-level link parameter, not part of custom_data. On a payment link external_id is its own field, separate from custom_data, and the external_id in the charge/webhook payload is read from that dedicated field (or from the charge's own external_id) — never from custom_data. Be aware that the Create Payment Link API does not currently persist external_id, so for links created through the API it stays null on the link and on the resulting subscription charges. To tie payments back to a user in your system, match on customer_details.email or on your own subscription_id.
One subscriber per subscription is the recommended API pattern. Creating a dedicated subscription object per customer keeps the subscriber-to-user mapping unambiguous and makes per-customer changes (cancel, change plan) straightforward.

Raw sample

{
  "status": "captured",
  "id": "PAY-E0A56BAA96",
  "amount": 2,
  "amount_currency": "AED",
  "refund_amount": 0,
  "refund_status": "No refund",
  "custom_data": {},
  "created_date": "2026-01-27-05-07-07",
  "subscription_id": "MPB-SUB-DC96DB2E95",
  "settlement_amount": "1.10",
  "settlement_currency": "AED",
  "settlement_date": "2026-02-03",
  "customer_details": {
    "name": "test test",
    "email": "[email protected]",
    "phone_number": "-",
    "comment": "-"
  },
  "payment_method": {
    "card_id": "CARD-71D9F4C239",
    "type": "CREDIT VISA",
    "card_holder_name": "Test Test",
    "card_last4": "4242",
    "card_expiry_month": "12",
    "card_expiry_year": "2033",
    "origin": "International card"
  },
  "settlement_fee": "AED 0.86",
  "settlement_vat": "AED 0.04",
  "payment_link_id": "MB-LINK-179673DBD0",
  "payment_link_url": "https://sandbox.dev.business.mamopay.com/pay/mamo-c4e3a1",
  "external_id": null,
  "billing_descriptor": "Mamo*Mamo Dubai",
  "error_code": null,
  "error_message": null,
  "next_payment_date": "03/02/2026",
  "event_type": "subscription.succeeded"
}

Field Descriptions

Field	Type	Description
status	String	Payment status (captured, failed, pending)
id	String	Unique payment identifier
amount	Number	Payment amount
amount_currency	String	Currency code for the payment amount
refund_amount	Number	Amount that has been refunded
refund_status	String	Refund status description
custom_data	Dictionary	Custom data associated with the payment
created_date	String (Format: YYYY-MM-DD-HH-MM-SS)	Payment creation date and time
subscription_id	String	Unique subscription identifier
settlement_amount	String	Amount to be settled after fees
settlement_currency	String	Currency for settlement
settlement_date	String (Format: YYYY-MM-DD)	Date when settlement will occur
customer_details	Dictionary	Customer information (`name`, `email`, `phone_number`, `comment`)
payment_method	Dictionary	Payment method details (`card_id`, `type`, `card_holder_name`, `card_last4`, `card_expiry_month`, `card_expiry_year`, `origin`)
settlement_fee	String	Fee amount for settlement
settlement_vat	String	VAT amount for settlement
payment_link_id	String	Associated payment link identifier
payment_link_url	String	URL of the associated payment link
external_id	String	External identifier if provided
billing_descriptor	String	Descriptor that appears on customer's bank statement
error_code	String	Error code if payment failed
error_message	String	Error message if payment failed
next_payment_date	String (Format: DD/MM/YYYY)	Date of the next scheduled payment
event_type	String	Webhook event type (subscription.succeeded, subscription.failed, etc.)