Settlement Notification Webhook

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 Security and signature validation.

Body Parameters — common envelope

Every settlement webhook shares the same top-level envelope:

number

required

HTTP Status Code. Always 200.

boolean

required

Indicates a successful event. Always true.

string

required

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

string

required

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

object

required

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

`data.settlement` (present on all events)

object

required

The settlement batch the event relates to.

Show settlement fields

integer

required

Unique settlement ID. Example: 1234

string

required

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

string

required

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

string

required

Settlement status. "completed" for completed settlements.

string

required

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

string

required

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

boolean

required

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

string

required

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

string

required

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

number

required

Total net amount of the settled transactions. Example: 1000000

number

required

Sum of admin fees across the batch. Example: 5000

number

required

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

number

required

Sum of SingaPay margin across the batch. Example: 2000

number

required

Settlement transfer fee. Non-zero only for the bank-account method; 0 for all other methods.

number

required

Net amount transferred: amount - settlement_fee. Example: 1000000

number

required

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

string

required

ISO 4217 currency code. Always "IDR".

string

Bank transfer status for the bank-account method: "pending", "success", or "failed". null for all other methods.

string

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

string

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

object

required

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

Show recipient fields

string

Recipient bank code. Example: "BRI"

string

Recipient account number.

string

Recipient account holder name.

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

integer

required

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

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

object

required

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

Show refund fields

integer

required

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

string

required

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

integer

required

ID of the underlying transaction. Example: 42

string

required

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

integer

Account the balance movement applied to. May be null.

object

required

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

Show net_amount fields

number

required

Net amount value. Example: 95000

string

required

ISO 4217 currency code. Always "IDR".

boolean

required

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

boolean

required

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

string

Admin who performed the refund. May be null.

string

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

string

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

string

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

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 populated only for the bank-account method and are null for all other methods. 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.

Getting Started

Security

Accept Money

Send Money

Transaction Records

Money Accounts

Webhook

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

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