Settlement Notification Webhook - Singapay Documentation

Accounting Operation — This webhook fires on settlement lifecycle events (completion, refund, refund cancellation). It reports money movements between your pending_balance, available_balance, and your bank account.

Information

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

SingaPay sends a POST request to your configured settlement_notif_url whenever a settlement batch reaches a final state, or when a settled transaction is refunded / has its refund cancelled.

This webhook may share a callback URL with other event types. Always route by the event value in the body. See Shared webhook endpoints.

Events

This single webhook covers three settlement events, distinguished by the event field:

`event`	Fired when	`data` contains
`settlement.completed`	A settlement batch is completed — either a sequential settlement is approved by Finance, or a parallel (auto) settlement is created by the scheduler.	`settlement`, `total_transactions`
`settlement.refunded`	A single settled transaction is refunded back from your balance (settlement method `balance` / `auto-balance` only).	`settlement`, `refund`
`settlement.refund_cancelled`	A previous refund is cancelled and the balance is restored.	`settlement`, `refund`

Settlement currently supports money-in transactions only (Virtual Account, QRIS, Payment Link, E-Wallet). Refund events apply only to settlements using the balance or auto-balance method.

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 for settlement webhooks is a randomly generated string — not a user access token. Settlement events are triggered by an admin approval, a scheduler, or a refund action (system events), not a user request. Extract the token as-is and use it in the string to sign. See How to Validate Signature below.

Body Parameters — common envelope

Every settlement webhook shares the same top-level envelope:

status

number

required

HTTP Status Code. Always 200.

success

boolean

required

Indicates a successful event. Always true.

event

string

required

Event type identifier. One of "settlement.completed", "settlement.refunded", "settlement.refund_cancelled".

timestamp

string

required

Event timestamp in format "d M Y H:i:s". Example: "18 Jun 2026 10:00:00"

data

object

required

Container for the settlement details (and, for refund events, the refund details).

`data.settlement` (present on all events)

settlement

object

required

The settlement batch the event relates to.

Show settlement fields

integer

required

Unique settlement ID. Example: 1234

reference_no

string

required

Settlement reference number. Format SETTLEMENT-{merchant_id}-{uniqid}. Example: "SETTLEMENT-1-ABC123"

title

string

required

Human-readable batch title. Example: "Settlement Acme (01 Jun 2026 - 17 Jun 2026)"

status

string

required

Settlement status. "completed" for completed settlements.

settlement_type

string

required

Transaction scope of the batch. One of "ALL", "VA", "QRIS", "EWALLET".

settlement_method

string

required

How funds were moved. One of "balance", "bank-account", "auto-balance".

is_auto_created

boolean

required

true if this batch was created automatically by parallel (auto) settlement; false for sequential settlements approved by Finance.

start_date

string

required

Start of the transaction date range covered. Format "d M Y H:i:s".

end_date

string

required

End of the transaction date range covered. Format "d M Y H:i:s".

amount

number

required

Total net amount of the settled transactions. Example: 1000000

total_admin_fee

number

required

Sum of admin fees across the batch. Example: 5000

total_vendor_fee

number

required

Sum of payment-vendor fees across the batch. Example: 3000

total_our_margin

number

required

Sum of SingaPay margin across the batch. Example: 2000

settlement_fee

number

required

Settlement transfer fee. Non-zero only for the bank-account method; 0 for balance / auto-balance.

total_to_transfer

number

required

Net amount transferred: amount - settlement_fee. Example: 1000000

total_refunded

number

required

Accumulated net amount that has been refunded from this settlement. Example: 0

currency

string

required

ISO 4217 currency code. Always "IDR".

transfer_status

string

Bank transfer status for the bank-account method: "pending", "success", or "failed". null for balance / auto-balance methods.

approved_by

string

Who completed the settlement. The approver’s name for sequential settlements, or "SYSTEM" for auto settlements.

approved_at

string

Timestamp the settlement was completed. Format "d M Y H:i:s".

recipient

object

required

Destination bank account (populated only for the bank-account method; otherwise all fields are null).

Show recipient fields

bank_code

string

Recipient bank code. Example: "BRI"

account_number

string

Recipient account number.

account_name

string

Recipient account holder name.

`data.total_transactions` (`settlement.completed` only)

total_transactions

integer

required

Number of transactions included in the completed settlement batch. Example: 5

`data.refund` (`settlement.refunded` & `settlement.refund_cancelled` only)

refund

object

required

Details of the individual transaction that was refunded or had its refund cancelled.

Show refund fields

settlement_detail_id

integer

required

ID of the settlement detail row (the transaction’s line within the batch). Example: 987

transaction_type

string

required

Class name of the underlying transaction. One of "VATransaction", "QrisTransaction", "PaymentLinkHistory", "EwalletTransaction", "PaymentLinkingTransaction".

transaction_id

integer

required

ID of the underlying transaction. Example: 42

transaction_reff

string

required

Reference of the underlying transaction. Example: "INV-2026-001"

account_id

integer

Account the balance movement applied to. May be null.

net_amount

object

required

Net amount deducted (refund) or restored (refund cancelled).

Show net_amount fields

value

number

required

Net amount value. Example: 95000

currency

string

required

ISO 4217 currency code. Always "IDR".

is_refunded

boolean

required

true once the detail has been refunded. Remains true even after a refund is cancelled.

is_refund_cancelled

boolean

required

true if the refund has been cancelled. false for an active refund.

refunded_by

string

Admin who performed the refund. May be null.

refunded_at

string

Timestamp the refund was performed. Format "d M Y H:i:s". May be null.

refund_cancelled_by

string

Admin who cancelled the refund. null for settlement.refunded.

refund_cancelled_at

string

Timestamp the refund was cancelled. Format "d M Y H:i:s". null for settlement.refunded.

actor

string

The admin who triggered this specific event (refunder or canceller). May be null.

Payload Examples

settlement.completed

{
  "status": 200,
  "success": true,
  "event": "settlement.completed",
  "timestamp": "18 Jun 2026 10:00:00",
  "data": {
    "settlement": {
      "id": 1234,
      "reference_no": "SETTLEMENT-1-ABC123",
      "title": "Settlement Acme (01 Jun 2026 - 17 Jun 2026)",
      "status": "completed",
      "settlement_type": "ALL",
      "settlement_method": "balance",
      "is_auto_created": false,
      "start_date": "01 Jun 2026 00:00:00",
      "end_date": "17 Jun 2026 23:59:59",
      "amount": 1000000,
      "total_admin_fee": 5000,
      "total_vendor_fee": 3000,
      "total_our_margin": 2000,
      "settlement_fee": 0,
      "total_to_transfer": 1000000,
      "total_refunded": 0,
      "currency": "IDR",
      "transfer_status": null,
      "approved_by": "Jane Finance",
      "approved_at": "18 Jun 2026 10:00:00",
      "recipient": {
        "bank_code": null,
        "account_number": null,
        "account_name": null
      }
    },
    "total_transactions": 5
  }
}

settlement.completed (bank-account)

{
  "status": 200,
  "success": true,
  "event": "settlement.completed",
  "timestamp": "18 Jun 2026 10:05:00",
  "data": {
    "settlement": {
      "id": 1240,
      "reference_no": "SETTLEMENT-1-XYZ789",
      "title": "Settlement Acme (17 Jun 2026 - 17 Jun 2026)",
      "status": "completed",
      "settlement_type": "VA",
      "settlement_method": "bank-account",
      "is_auto_created": false,
      "start_date": "17 Jun 2026 00:00:00",
      "end_date": "17 Jun 2026 23:59:59",
      "amount": 2000000,
      "total_admin_fee": 10000,
      "total_vendor_fee": 6000,
      "total_our_margin": 4000,
      "settlement_fee": 13000,
      "total_to_transfer": 1987000,
      "total_refunded": 0,
      "currency": "IDR",
      "transfer_status": "success",
      "approved_by": "Jane Finance",
      "approved_at": "18 Jun 2026 10:05:00",
      "recipient": {
        "bank_code": "BRI",
        "account_number": "1234567890",
        "account_name": "PT Acme Indonesia"
      }
    },
    "total_transactions": 8
  }
}

settlement.refunded

{
  "status": 200,
  "success": true,
  "event": "settlement.refunded",
  "timestamp": "19 Jun 2026 09:30:00",
  "data": {
    "settlement": {
      "id": 1234,
      "reference_no": "SETTLEMENT-1-ABC123",
      "title": "Settlement Acme (01 Jun 2026 - 17 Jun 2026)",
      "status": "completed",
      "settlement_type": "ALL",
      "settlement_method": "balance",
      "is_auto_created": false,
      "start_date": "01 Jun 2026 00:00:00",
      "end_date": "17 Jun 2026 23:59:59",
      "amount": 1000000,
      "total_admin_fee": 5000,
      "total_vendor_fee": 3000,
      "total_our_margin": 2000,
      "settlement_fee": 0,
      "total_to_transfer": 1000000,
      "total_refunded": 95000,
      "currency": "IDR",
      "transfer_status": null,
      "approved_by": "Jane Finance",
      "approved_at": "18 Jun 2026 10:00:00",
      "recipient": {
        "bank_code": null,
        "account_number": null,
        "account_name": null
      }
    },
    "refund": {
      "settlement_detail_id": 987,
      "transaction_type": "VATransaction",
      "transaction_id": 42,
      "transaction_reff": "INV-2026-001",
      "account_id": 7,
      "net_amount": {
        "value": 95000,
        "currency": "IDR"
      },
      "is_refunded": true,
      "is_refund_cancelled": false,
      "refunded_by": "Bob Admin",
      "refunded_at": "19 Jun 2026 09:30:00",
      "refund_cancelled_by": null,
      "refund_cancelled_at": null,
      "actor": "Bob Admin"
    }
  }
}

settlement.refund_cancelled

{
  "status": 200,
  "success": true,
  "event": "settlement.refund_cancelled",
  "timestamp": "19 Jun 2026 11:00:00",
  "data": {
    "settlement": {
      "id": 1234,
      "reference_no": "SETTLEMENT-1-ABC123",
      "title": "Settlement Acme (01 Jun 2026 - 17 Jun 2026)",
      "status": "completed",
      "settlement_type": "ALL",
      "settlement_method": "balance",
      "is_auto_created": false,
      "start_date": "01 Jun 2026 00:00:00",
      "end_date": "17 Jun 2026 23:59:59",
      "amount": 1000000,
      "total_admin_fee": 5000,
      "total_vendor_fee": 3000,
      "total_our_margin": 2000,
      "settlement_fee": 0,
      "total_to_transfer": 1000000,
      "total_refunded": 0,
      "currency": "IDR",
      "transfer_status": null,
      "approved_by": "Jane Finance",
      "approved_at": "18 Jun 2026 10:00:00",
      "recipient": {
        "bank_code": null,
        "account_number": null,
        "account_name": null
      }
    },
    "refund": {
      "settlement_detail_id": 987,
      "transaction_type": "VATransaction",
      "transaction_id": 42,
      "transaction_reff": "INV-2026-001",
      "account_id": 7,
      "net_amount": {
        "value": 95000,
        "currency": "IDR"
      },
      "is_refunded": true,
      "is_refund_cancelled": true,
      "refunded_by": "Bob Admin",
      "refunded_at": "19 Jun 2026 09:30:00",
      "refund_cancelled_by": "Bob Admin",
      "refund_cancelled_at": "19 Jun 2026 11:00:00",
      "actor": "Bob Admin"
    }
  }
}

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 settlement_notif_url path when building StringToSign. Handle duplicate deliveries idempotently using stable identifiers from the payload — for settlement.completed use data.settlement.reference_no; for refund events combine data.settlement.reference_no with data.refund.settlement_detail_id (and the event).

Settlement Specific Notes

One callback URL, three events

All three events are delivered to the same settlement_notif_url. Always branch on the event field. A settlement.completed payload has total_transactions; refund events have a refund object instead.

Sequential vs auto settlement

is_auto_created = false means a sequential settlement approved by Finance (approved_by is the approver’s name). is_auto_created = true means a parallel auto settlement created by the scheduler (approved_by = "SYSTEM"). Both arrive as settlement.completed.

amount vs total_to_transfer

amount is the total net amount of the settled transactions. total_to_transfer is what was actually moved out — amount - settlement_fee. The settlement_fee is only non-zero for the bank-account method.

Refunds only for balance methods

settlement.refunded and settlement.refund_cancelled fire only for settlements using the balance or auto-balance method. Refund deducts (and cancel restores) the transaction’s net amount from your available_balance — fees are not refunded.

Refund state via flags

Track refund state with is_refunded and is_refund_cancelled. An active refund is is_refunded=true, is_refund_cancelled=false. A cancelled refund is is_refunded=true, is_refund_cancelled=true — note is_refunded stays true.

Nullable fields

transfer_status and the recipient.* fields are null for balance / auto-balance settlements. Actor fields (refunded_by, refund_cancelled_by, actor) and account_id may be null. Handle null gracefully.

Timestamp format & timezone

All timestamps (timestamp, approved_at, start_date, end_date, refunded_at, refund_cancelled_at) use the format "d M Y H:i:s" (e.g. "18 Jun 2026 10:00:00") in Asia/Jakarta (WIB) timezone — not UTC.

​Information

​Events

​Request Details

​Headers

​Body Parameters — common envelope

​data.settlement (present on all events)

​data.total_transactions (settlement.completed only)

​data.refund (settlement.refunded & settlement.refund_cancelled only)

​Payload Examples

​Security and responses

​Settlement Specific Notes

Information

Events

Request Details

Headers

Body Parameters — common envelope

`data.settlement` (present on all events)

`data.total_transactions` (`settlement.completed` only)

`data.refund` (`settlement.refunded` & `settlement.refund_cancelled` only)

Payload Examples

Security and responses

Settlement Specific Notes