Subscription Cycle Webhook - Singapay Documentation

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.

status

number

required

HTTP-style status code. Always 200.

success

boolean

required

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

event

string

required

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

timestamp

string

required

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

data

object

required

Event payload.

Show data fields

plan

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"

subscription_id

string

required

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

merchant_reff_no

string

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

name

string

required

Plan display name. Example: "Premium Monthly"

amount

number

required

Per-cycle charge amount. Example: 150000

currency

string

required

ISO 4217 currency code. Example: "IDR"

status

string

required

Current plan status. Example: "active"

parent_plan_id

string

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

retry_policy

object

required

Plan-level retry policy.

Show retry_policy fields

max_attempts

integer

required

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

interval_days

integer

required

Days between consecutive retries. Example: 3

failed_payment_action

string

required

"continue_plan" or "stop_plan".

bill

object

required

The specific cycle bill this event relates to.

Show bill fields

integer

required

Internal bill ID. Example: 12345

bill_number

string

required

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

status

string

required

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

total_amount

number

required

Charge amount for this bill. Example: 150000

currency

string

required

ISO 4217 currency code. Always "IDR" today.

due_date

string

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

paid_date

string

Paid timestamp (ISO 8601). null on payment_failed.

failure_reason

string

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

payment_reference

string

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

retry

object

required

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

Show retry fields

attempt

integer

required

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

max_attempts

integer

required

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

attempts_remaining

integer

required

max_attempts - attempt, clamped to 0.

max_attempts_reached

boolean

required

true when no more retries will fire.

interval_days

integer

required

Days between retries.

failed_payment_action

string

required

"continue_plan" or "stop_plan".

next_retry_at

string

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

last_attempt_at

string

Most recent retry attempt timestamp (ISO 8601).

history

array

required

Chronological list of retry attempts on this bill.

Show history item fields

attempt

integer

required

Retry sequence number (1-indexed).

status

string

required

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

retry_date

string

When this retry was executed (ISO 8601).

next_retry_date

string

When the next retry is scheduled (ISO 8601).

failure_reason

string

Reason this particular retry failed.

cycle

object

The cycle this bill belongs to.

Show cycle fields

integer

required

Internal cycle ID. Example: 7890

cycle_number

integer

required

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

status

string

required

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

period_start

string

Cycle period start (ISO 8601).

period_end

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"
    }
  }
}

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.

status

number

required

Always 200.

success

boolean

required

Always true.

event

string

required

"subscription.plan.status_changed"

timestamp

string

required

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

data

object

required

Show data fields

plan

object

required

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

previous_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.

​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