Subscription Cycle Webhook

Dedicated URL — Unlike transaction_notif_url which is shared across VA, QRIS, Payment Link, and E-Wallet events, the subscription_cycle_notif_url is exclusively for subscription events. Configure it separately in the merchant dashboard.

Information

Method	Path	Format	Authentication
POST	`https://your-webhook-url/callback`	json	HMAC SHA512 Signature

This webhook fires whenever one of the following happens on any subscription plan:

A cycle charge succeeds — initial charge after card linking, every recurring cycle, or a successful retry
A cycle charge fails — initial attempt and every retry attempt are delivered separately
The plan status changes — e.g. suspended after retries exhausted, completed after the last cycle, or cancelled (including system-initiated auto-cancel for charge_immediately = true plans rejected by the issuer)

The event field distinguishes between them.

Events

Event	When it fires	`success` field
`subscription.cycle.payment_success`	A cycle bill is paid (initial, recurring, or successful retry)	`true`
`subscription.cycle.payment_failed`	A cycle bill attempt fails — fired on every attempt including each retry	`true` (HTTP `200`)
`subscription.plan.status_changed`	The plan transitions to `suspended`, `cancelled`, or `completed`	`true`

success: true on payment_failed events indicates the webhook itself was emitted successfully — not that the charge succeeded. Always check the event field to determine the actual outcome.

Request Details

Headers

Field	Value	Type	Mandatory	Description
`Content-Type`	`application/json`	Alphabetic	Yes	Specifies JSON format for the request body
`User-Agent`	`SingaPaymentGateway/1.0`	Alphabetic	Yes	Identifies the source of the webhook
`Accept`	`application/json`	Alphabetic	Yes	Expected response format
`X-PARTNER-ID`	—	Alphanumeric	Yes	Your API Key from the merchant dashboard
`X-Signature`	—	Alphanumeric	Yes	HMAC SHA512 signature (128 chars) for request verification
`X-Timestamp`	—	Numeric	Yes	Unix timestamp in seconds when the request was sent
`Authorization`	`Bearer <random_token>`	Alphanumeric	Yes	System-generated random bearer token; used as a component in the signature

The Authorization token is a randomly generated string — not a user access token. Extract it as-is and use it in the string to sign. The signing scheme is identical to other SingaPay webhooks. See How to Validate Signature below.

Body Parameters — Payment Success / Failed

These two events share the same body shape. The only difference is the event value and, on failure, whether bill.retry indicates more attempts are coming.

number

required

HTTP-style status code. Always 200.

boolean

required

Always true — indicates the webhook was emitted successfully, not the charge outcome.

string

required

"subscription.cycle.payment_success" or "subscription.cycle.payment_failed".

string

required

Event timestamp in format "d M Y H:i:s". Example: "01 May 2026 00:00:15"

object

required

Event payload.

Show data fields

object

required

Snapshot of the subscription plan at the time of the event.

Show plan fields

string

required

Subscription Plan ID (26-char ULID). Example: "01JAB3CD4E5F6G7H8J9K0M1N2"

string

required

Globally unique merchant-supplied plan reference. Example: "PLAN-20260420-001"

string

Merchant-side reference label echoed from plan creation. null if not set.

string

required

Plan display name. Example: "Premium Monthly"

number

required

Per-cycle charge amount. Example: 150000

string

required

ISO 4217 currency code. Example: "IDR"

string

required

Current plan status. Example: "active"

string

ID of the previous plan superseded via upgrade. null if not an upgrade.

object

required

Plan-level retry policy.

Show retry_policy fields

integer

required

Max retry attempts after the initial charge fails. Example: 3

integer

required

Days between consecutive retries. Example: 3

string

required

"continue_plan" or "stop_plan".

object

required

The specific cycle bill this event relates to.

Show bill fields

integer

required

Internal bill ID. Example: 12345

string

required

Human-readable bill number — also used as the webhook reff_no and idempotency key. Example: "SUBBILL-202605-0001"

string

required

"pending" | "processing" | "paid" | "failed"

number

required

Charge amount for this bill. Example: 150000

string

required

ISO 4217 currency code. Always "IDR" today.

string

Cycle due date (ISO 8601). Example: "2026-05-01T00:00:00+07:00"

string

Paid timestamp (ISO 8601). null on payment_failed.

string

Human-readable failure reason. Present on payment_failed. Example: "card_declined"

string

Provider-side reference for this charge. Example: "IONPAYTEST01202604201200000001"

object

required

Per-bill retry state combining the plan policy with the live attempt counter.

Show retry fields

integer

required

How many retry attempts have been made so far. 0 on the initial attempt.

integer

required

Max retry attempts (mirrors plan.retry_policy.max_attempts).

integer

required

max_attempts - attempt, clamped to 0.

boolean

required

true when no more retries will fire.

integer

required

Days between retries.

string

required

"continue_plan" or "stop_plan".

string

Next retry timestamp (ISO 8601). null when no more retries are scheduled.

string

Most recent retry attempt timestamp (ISO 8601).

array

required

Chronological list of retry attempts on this bill.

Show history item fields

integer

required

Retry sequence number (1-indexed).

string

required

"pending" | "processing" | "paid" | "failed"

string

When this retry was executed (ISO 8601).

string

When the next retry is scheduled (ISO 8601).

string

Reason this particular retry failed.

object

The cycle this bill belongs to.

Show cycle fields

integer

required

Internal cycle ID. Example: 7890

integer

required

1-indexed cycle number within the plan. Example: 3

string

required

"pending" | "paid" | "failed" | "skipped"

string

Cycle period start (ISO 8601).

string

Cycle period end (ISO 8601).

Payload Examples — Payment Events

{
  "status": 200,
  "success": true,
  "event": "subscription.cycle.payment_success",
  "timestamp": "01 May 2026 00:00:15",
  "data": {
    "plan": {
      "id": "01JAB3CD4E5F6G7H8J9K0M1N2",
      "subscription_id": "PLAN-20260420-001",
      "merchant_reff_no": "SUB-CUST-ACME-001",
      "name": "Premium Monthly",
      "amount": 150000,
      "currency": "IDR",
      "status": "active",
      "parent_plan_id": null,
      "retry_policy": {
        "max_attempts": 3,
        "interval_days": 3,
        "failed_payment_action": "continue_plan"
      }
    },
    "bill": {
      "id": 12345,
      "bill_number": "SUBBILL-202605-0001",
      "status": "paid",
      "total_amount": 150000,
      "currency": "IDR",
      "due_date": "2026-05-01T00:00:00+07:00",
      "paid_date": "2026-05-01T00:00:15+07:00",
      "failure_reason": null,
      "payment_reference": "IONPAYTEST01202605010000000001",
      "retry": {
        "attempt": 0,
        "max_attempts": 3,
        "attempts_remaining": 3,
        "max_attempts_reached": false,
        "interval_days": 3,
        "failed_payment_action": "continue_plan",
        "next_retry_at": null,
        "last_attempt_at": null,
        "history": []
      }
    },
    "cycle": {
      "id": 7890,
      "cycle_number": 3,
      "status": "paid",
      "period_start": "2026-05-01T00:00:00+07:00",
      "period_end": "2026-06-01T00:00:00+07:00"
    }
  }
}

{
  "status": 200,
  "success": true,
  "event": "subscription.cycle.payment_failed",
  "timestamp": "01 May 2026 00:00:20",
  "data": {
    "plan": {
      "id": "01JAB3CD4E5F6G7H8J9K0M1N2",
      "subscription_id": "PLAN-20260420-001",
      "merchant_reff_no": "SUB-CUST-ACME-001",
      "name": "Premium Monthly",
      "amount": 150000,
      "currency": "IDR",
      "status": "active",
      "parent_plan_id": null,
      "retry_policy": {
        "max_attempts": 3,
        "interval_days": 3,
        "failed_payment_action": "continue_plan"
      }
    },
    "bill": {
      "id": 12346,
      "bill_number": "SUBBILL-202605-0002",
      "status": "failed",
      "total_amount": 150000,
      "currency": "IDR",
      "due_date": "2026-05-01T00:00:00+07:00",
      "paid_date": null,
      "failure_reason": "card_declined",
      "payment_reference": "IONPAYTEST01202605010000000002",
      "retry": {
        "attempt": 1,
        "max_attempts": 3,
        "attempts_remaining": 2,
        "max_attempts_reached": false,
        "interval_days": 3,
        "failed_payment_action": "continue_plan",
        "next_retry_at": "2026-05-04T00:00:00+07:00",
        "last_attempt_at": "2026-05-01T00:00:20+07:00",
        "history": [
          {
            "attempt": 1,
            "status": "failed",
            "retry_date": "2026-05-01T00:00:20+07:00",
            "next_retry_date": "2026-05-04T00:00:00+07:00",
            "failure_reason": "card_declined"
          }
        ]
      }
    },
    "cycle": {
      "id": 7891,
      "cycle_number": 4,
      "status": "pending",
      "period_start": "2026-05-01T00:00:00+07:00",
      "period_end": "2026-06-01T00:00:00+07:00"
    }
  }
}

{
  "status": 200,
  "success": true,
  "event": "subscription.cycle.payment_failed",
  "timestamp": "07 May 2026 00:00:20",
  "data": {
    "plan": { "...": "..." },
    "bill": {
      "id": 12346,
      "bill_number": "SUBBILL-202605-0002",
      "status": "failed",
      "total_amount": 150000,
      "currency": "IDR",
      "failure_reason": "card_declined",
      "retry": {
        "attempt": 3,
        "max_attempts": 3,
        "attempts_remaining": 0,
        "max_attempts_reached": true,
        "interval_days": 3,
        "failed_payment_action": "stop_plan",
        "next_retry_at": null,
        "last_attempt_at": "2026-05-07T00:00:20+07:00",
        "history": [
          { "attempt": 1, "status": "failed", "retry_date": "2026-05-01T00:00:20+07:00", "failure_reason": "card_declined" },
          { "attempt": 2, "status": "failed", "retry_date": "2026-05-04T00:00:20+07:00", "failure_reason": "card_declined" },
          { "attempt": 3, "status": "failed", "retry_date": "2026-05-07T00:00:20+07:00", "failure_reason": "card_declined" }
        ]
      }
    }
  }
}

When bill.retry.max_attempts_reached is true and failed_payment_action is "stop_plan", expect a subsequent subscription.plan.status_changed event with plan.status: "suspended" to arrive shortly after.

Body Parameters — Plan Status Changed

Fires when the plan transitions to suspended, cancelled, or completed.

number

required

Always 200.

boolean

required

Always true.

string

required

"subscription.plan.status_changed"

string

required

Event timestamp in format "d M Y H:i:s". Example: "07 May 2026 00:05:00"

object

required

Show data fields

object

required

Plan snapshot — same shape as the plan block in payment events above. plan.status reflects the new status.

string

required

Status the plan was in before the transition. Example: "active"

Payload Example — Plan Status Changed

Plan suspended after retries exhausted

{
  "status": 200,
  "success": true,
  "event": "subscription.plan.status_changed",
  "timestamp": "07 May 2026 00:05:00",
  "data": {
    "plan": {
      "id": "01JAB3CD4E5F6G7H8J9K0M1N2",
      "subscription_id": "PLAN-20260420-001",
      "merchant_reff_no": "SUB-CUST-ACME-001",
      "name": "Premium Monthly",
      "amount": 150000,
      "currency": "IDR",
      "status": "suspended",
      "parent_plan_id": null,
      "retry_policy": {
        "max_attempts": 3,
        "interval_days": 3,
        "failed_payment_action": "stop_plan"
      }
    },
    "previous_status": "active"
  }
}

Security and responses

Return HTTP 200 promptly after validating the request. For retry behavior, see Webhook retry mechanism. Verify every webhook using Security and signature validation. Use your configured callback path when building StringToSign. Handle duplicate deliveries idempotently using stable identifiers from the payload (for example transaction_id or reff_no).

Idempotency

Use bill.bill_number as your primary idempotency key when storing successful deliveries. The same bill number may arrive more than once if your endpoint returned a non-2xx response and SingaPay retried the webhook delivery. For failed charge retries, the bill_number stays the same but bill.retry.attempt increments. Use the compound key (bill_number, retry.attempt) if you need per-attempt idempotency.

Important Notes

One event per attempt

Every retry attempt emits its own subscription.cycle.payment_failed (or payment_success on the attempt that finally clears). Monitor bill.retry.attempts_remaining to know whether another automatic attempt is coming.

Plan status events are separate

When retries are exhausted with failed_payment_action: stop_plan, expect a payment_failed event followed shortly by a plan.status_changed event with plan.status: "suspended". These are two distinct webhook deliveries.

Plan lineage after upgrades

After a PATCH upgrade, the new plan has a different plan.id but the same plan.subscription_id and plan.merchant_reff_no. The old plan’s ID is available on plan.parent_plan_id for reconciliation.

merchant_reff_no is optional

If you didn’t set merchant_reff_no at plan creation, it will be null on every cycle webhook. Set it during plan creation to have it echoed back reliably for your own tracking.

Currency is always IDR

bill.currency is always "IDR" today — card recurring runs in IDR only.

Getting Started

Security

Accept Money

Send Money

Transaction Records

Money Accounts

Webhook

Information

Events

Request Details

Headers

Body Parameters — Payment Success / Failed

Payload Examples — Payment Events

Body Parameters — Plan Status Changed

Payload Example — Plan Status Changed

Security and responses

Idempotency

Important Notes

​Information

​Events

​Request Details

​Headers

​Body Parameters — Payment Success / Failed

​Payload Examples — Payment Events

​Body Parameters — Plan Status Changed

​Payload Example — Plan Status Changed

​Security and responses

​Idempotency

​Important Notes

Information

Events

Request Details

Headers

Body Parameters — Payment Success / Failed

Payload Examples — Payment Events

Body Parameters — Plan Status Changed

Payload Example — Plan Status Changed

Security and responses

Idempotency

Important Notes