Callbacks (Webhooks)

Triyakom uses an outbound callback mechanism to notify partners of asynchronous transaction results. Partners must provide a reachable HTTPS endpoint to receive these notifications.

General Specifications

Item	Value
Direction	Triyakom → Partner
HTTP Method	`POST`
Content-Type	`application/json`
Acknowledgment	Partner must return HTTP 200
Retry	Exponential backoff (outbox-based) on non-2xx or timeout

Security & Signature Verification

Every callback request from Triyakom includes a digital signature to ensure data integrity and authenticity. Partners must verify this signature before processing the payload.

Headers Sent by Triyakom

Header	Description
`X-Timestamp`	Sending time in ISO-8601 format
`X-Nonce`	Unique UUID per request to prevent replay attacks
`X-Signature`	HMAC-SHA256 signature encoded in Base64

Signature Verification Steps

Step 1 — Hash the raw request body with SHA256 (lowercase hex):

SHA256(RawBody)

Step 2 — Assemble the StringToSign (fields joined by \n newline):

METHOD + "\n" + PATH + "\n" + X-Timestamp + "\n" + X-Nonce + "\n" + SHA256(RawBody)

Step 3 — Compute HMAC-SHA256 using the HmacSecret provided by Triyakom:

ExpectedSignature = Base64(HMAC-SHA256(HmacSecret, StringToSign))

Step 4 — Compare ExpectedSignature with the X-Signature header value. If they do not match, reject the request with HTTP 401.

⚠️ The raw body used for hashing must be byte-for-byte identical to the received HTTP body (same encoding, same whitespace). Both SHA256(RawBody) and the final signature must be computed over the exact bytes received.

1. Recurring Subscription Callback

Callback URL

Default callback URL configured for the partner during onboarding.

Event Types & Payloads

There are 5 event types that may be delivered via this callback.

A. Subscription Success

Triggered when a new subscription is successfully activated.

{
  "event_type": "Subscription",
  "status": "Success",
  "payment_method": "XL",
  "amount": 1110.0,
  "startDate": "2024-07-19T19:35:00+07:00",
  "nextRenewalDate": "2024-07-20T00:00:00+07:00",
  "msisdn": "6287800000000",
  "product_id": "DAILY_BASIC",
  "subscription_id": 1025,
  "transaction_id": "f7b199e3-178f-46fb-a9da-aff1b45c346e",
  "timestamp": "2024-07-19T19:35:05+07:00"
}

B. Renewal Success

Triggered when a recurring renewal charge is successfully completed.

{
  "event_type": "Renewal",
  "status": "Success",
  "payment_method": "XL",
  "amount": 1110.0,
  "nextRenewalDate": "2024-07-21T00:00:00+07:00",
  "msisdn": "6287800000000",
  "product_id": "DAILY_BASIC",
  "subscription_id": 1025,
  "transaction_id": "e8032d61-7f4d-4b7b-a3e5-bd708c0bae7e",
  "timestamp": "2024-07-20T00:05:00+07:00"
}

C. Renewal Failed

Triggered when a renewal charge fails (e.g. insufficient balance, grace period, or block).

{
  "event_type": "Renewal",
  "status": "Failed",
  "payment_method": "XL",
  "msisdn": "6287800000000",
  "product_id": "DAILY_BASIC",
  "subscription_id": 1025,
  "timestamp": "2024-07-20T00:05:00+07:00"
}

D. Unsubscribe Success

Triggered when a subscription is successfully cancelled.

{
  "event_type": "Unsubscribe",
  "status": "Success",
  "payment_method": "XL",
  "msisdn": "6287800000000",
  "product_id": "DAILY_BASIC",
  "subscription_id": 1025,
  "transaction_id": "60e476f9-baf0-4426-b1c3-5c5b494e4fd2",
  "timestamp": "2024-07-25T14:10:00+07:00"
}

E. Subscription Failed

Triggered when a new subscription activation fails.

{
  "event_type": "Subscription",
  "status": "Failed",
  "payment_method": "XL",
  "msisdn": "6287800000000",
  "product_id": "DAILY_BASIC",
  "timestamp": "2024-07-25T14:10:00+07:00"
}

Payload Field Reference

Field	Type	Present When	Description
`event_type`	string	Always	`Subscription`, `Renewal`, or `Unsubscribe`
`status`	string	Always	`Success` or `Failed`
`payment_method`	string	Always	e.g. `XL`
`amount`	float	Success only	Charged amount in IDR
`msisdn`	string	Always	Customer mobile number
`product_id`	string	Always	Product identifier
`subscription_id`	integer	Always	Internal subscription ID from Triyakom
`transaction_id`	string (uuid)	Success only	Transaction ID for reconciliation
`startDate`	string (ISO-8601)	Subscription Success	Subscription start date
`nextRenewalDate`	string (ISO-8601)	Subscription/Renewal Success	Scheduled next renewal date
`timestamp`	string (ISO-8601)	Always	Time the event was recorded

2. On-Demand Charge Result Callback

Callback URL

Provided per request via callback_url field in the Create Charge request body, or a default callback URL configured for the partner during onboarding if not specified.

Possible `status` Values

Status	Description
`Paid`	Charge was successful
`Failed`	Charge failed
`Canceled`	Charge was cancelled
`Insufficient Balance`	Customer does not have sufficient balance

Payload

{
  "status": "Paid",
  "failure_reason": "",
  "failure_message": "",
  "event_type": "OneTimePurchase",
  "payment_method": "XL",
  "amount": 3330.0,
  "msisdn": "6287800000000",
  "transaction_date": "2026-05-08T10:01:42+07:00",
  "item_id": "IM0002",
  "item_name": "MIA 3330",
  "item_description": "MIA 3330",
  "partner_ref_id": "0b5efb01-3ee5-491c-95ee-088316ca67b0",
  "transaction_id": "E01A7B3F-2B0C-42E7-9918-FA3333F41797"
}

Payload Field Reference

Field	Type	Description
`status`	string	`Paid`, `Failed`, `Canceled`, or `Insufficient Balance`
`failure_reason`	string	Short failure code. Empty string if successful.
`failure_message`	string	Detailed failure description. Empty string if successful.
`event_type`	string	Always `OneTimePurchase`
`payment_method`	string	e.g. `XL`
`amount`	float	Charged amount in IDR
`msisdn`	string	Customer mobile number
`transaction_date`	string (ISO-8601)	Date and time of the charge
`item_id`	string	Item identifier
`item_name`	string	Item name
`item_description`	string	Item description
`partner_ref_id`	string (uuid)	Echo of `partner_ref_id` from Create Charge request
`transaction_id`	string (uuid)	Triyakom transaction ID for reconciliation

Partner Response Requirements

Regardless of callback type, partners must respond as follows:

Success Response (HTTP 200)

{
  "status": "SUCCESS",
  "message": "Notification received"
}

Field	Description
`status`	Must be `SUCCESS`
`message`	Freeform text for logging or audit purposes. Recommended: `"Notification received"` or `"Already processed (duplicate)"`

Error Response (HTTP 4xx / 5xx)

{
  "status": "FAILED",
  "message": "Invalid signature / Database error"
}

Field	Description
`status`	Anything other than `SUCCESS`. Recommended: `FAILED` or `ERROR`
`message`	Detailed failure reason to facilitate debugging

⚠️ If the partner returns a non-2xx response or times out, Triyakom will retry delivery using an outbox-based exponential backoff mechanism.

General Specifications#

Security & Signature Verification#

Headers Sent by Triyakom#

Signature Verification Steps#

1. Recurring Subscription Callback#

Callback URL#

Event Types & Payloads#

A. Subscription Success#

B. Renewal Success#

C. Renewal Failed#

D. Unsubscribe Success#

E. Subscription Failed#

Payload Field Reference#

2. On-Demand Charge Result Callback#

Callback URL#

Possible status Values#

Payload#

Payload Field Reference#

Partner Response Requirements#

Success Response (HTTP 200)#

Error Response (HTTP 4xx / 5xx)#

General Specifications

Security & Signature Verification

Headers Sent by Triyakom

Signature Verification Steps

1. Recurring Subscription Callback

Callback URL

Event Types & Payloads

A. Subscription Success

B. Renewal Success

C. Renewal Failed

D. Unsubscribe Success

E. Subscription Failed

Payload Field Reference

2. On-Demand Charge Result Callback

Callback URL

Possible `status` Values

Payload

Payload Field Reference

Partner Response Requirements

Success Response (HTTP 200)

Error Response (HTTP 4xx / 5xx)