Webhook events and payloads

Understand the webhook event envelope and inspect payment, payout, and refund examples.

Every webhook request body is a JSON event envelope. Route the event using X-SFPY-EVENT-TYPE or webhookEventType, deduplicate it using X-SFPY-EVENT-ID or identifier, and then inspect subject.payment for the affected resource.

Event envelope

Field	Type	Description
source	string	Event producer. Currently SAFEPAY_RAAST.
kind	string	Broad category: PAYMENT_EVENT, REFUND_EVENT, or SETTLEMENT_EVENT.
code	string	Raast event code corresponding to the state change.
version	string	Payload version. Currently V1_0_0.
timestamp	string	UTC RFC 3339 time at which the event was created. This differs from X-SFPY-TIMESTAMP, which is generated for each delivery attempt.
identifier	string	Unique event ID; matches X-SFPY-EVENT-ID.
partnerId	string	Partner identifier when the aggregator belongs to a partner. It can be empty.
aggregatorId	string	Aggregator identifier; matches X-SFPY-AGGREGATOR-ID.
subject	object	Resource snapshot associated with the event. Webhook events currently carry it in subject.payment.
destinations	array	Delivery-routing metadata. Do not use it for business logic.
raastChannel	string	Internal channel metadata. It can be empty.
webhookEventType	string	Public event name; matches X-SFPY-EVENT-TYPE.

JSON property names use lower camel case. Protobuf int64 values, including payment amounts and internal numeric IDs, are serialized as JSON strings. Timestamps use RFC 3339 and enum values use their string names.

Treat payload evolution as additive. Ignore fields and enum values you do not recognize, and use webhookEventType rather than relying only on kind or code.

Complete payment.completed example

The following is a representative complete body generated by the current V1_0_0 serializer. Empty strings, empty arrays, and null nested resources are included because the serializer emits unpopulated fields.

{
  "source": "SAFEPAY_RAAST",
  "kind": "PAYMENT_EVENT",
  "code": "PAYMENT_CAPTURED",
  "version": "V1_0_0",
  "timestamp": "2026-09-14T10:15:30.123456Z",
  "identifier": "txnlog_5246fdcc-6c86-49bb-9da2-aa38262e0291",
  "partnerId": "partner_12345678-1234-1234-1234-123456789012",
  "aggregatorId": "agg_2288490a-2176-4de5-b373-0ffb6f8e2e6e",
  "subject": {
    "payment": {
      "id": "0",
      "token": "pm_12345678-1234-1234-1234-123456789012",
      "aggregatorId": "agg_2288490a-2176-4de5-b373-0ffb6f8e2e6e",
      "aggregatorMerchantId": "am_12345678-1234-1234-1234-123456789012",
      "qrCodeId": "",
      "orderId": "order-1042",
      "type": "RTP_NOW",
      "amount": "250000",
      "status": "P_CAPTURED",
      "uetr": "",
      "traceReference": "",
      "msgId": "",
      "instrId": "",
      "endToEndId": "",
      "pmtInfId": "",
      "requestId": "8e3df3ac-2607-4f3a-8a69-67e4efc284b3",
      "msgCreatedAt": "",
      "expiresAt": null,
      "createdAt": "2026-09-14T10:14:55Z",
      "updatedAt": "2026-09-14T10:15:30Z",
      "txnLogs": [],
      "paymentParties": [],
      "qrCode": null,
      "aggregatorMerchant": null,
      "refunds": [],
      "settlement": null,
      "paymentAuthorization": null,
      "aggregator": null,
      "isoOrderReference": ""
    }
  },
  "destinations": [],
  "raastChannel": "",
  "webhookEventType": "payment.completed"
}

The exact subject.payment snapshot can contain populated transaction logs, payment parties, QR details, merchant details, refunds, settlement details, authorization details, and aggregator details. Persist the entire event, but select only the fields your integration needs.

Refund event example

Refund lifecycle events use kind: REFUND_EVENT and include the payment plus its refund records. This focused example omits unrelated empty payment fields for readability; the delivered body uses the same complete envelope shown above.

{
  "source": "SAFEPAY_RAAST",
  "kind": "REFUND_EVENT",
  "code": "REFUND_COMPLETED",
  "version": "V1_0_0",
  "timestamp": "2026-09-14T11:04:22.834Z",
  "identifier": "txnlog_1a574d66-9bdf-48ae-a858-802951c46705",
  "partnerId": "partner_12345678-1234-1234-1234-123456789012",
  "aggregatorId": "agg_2288490a-2176-4de5-b373-0ffb6f8e2e6e",
  "subject": {
    "payment": {
      "token": "pm_12345678-1234-1234-1234-123456789012",
      "aggregatorId": "agg_2288490a-2176-4de5-b373-0ffb6f8e2e6e",
      "orderId": "order-1042",
      "type": "RTP_NOW",
      "amount": "250000",
      "status": "P_REFUNDED",
      "refunds": [
        {
          "id": "0",
          "token": "rfd_12345678-1234-1234-1234-123456789012",
          "paymentId": "pm_12345678-1234-1234-1234-123456789012",
          "amount": "250000",
          "type": "FULL_REFUND",
          "reason": "TechnicalProblem",
          "addtlInfo": "Customer refund",
          "status": "R_COMPLETED",
          "traceReference": "refund-trace-1042",
          "msgId": "refund-message-1042",
          "returnId": "return-1042",
          "requestId": "b27d5c04-6ad4-4fb6-b9fa-2ffc81ac5db8",
          "msgCreatedAt": "2026-09-14T11:03:58Z",
          "settleAt": "2026-09-14T11:04:20Z",
          "createdAt": "2026-09-14T11:03:57Z",
          "updatedAt": "2026-09-14T11:04:22Z"
        }
      ]
    }
  },
  "destinations": [],
  "raastChannel": "",
  "webhookEventType": "refund.completed"
}

Payment-level events payment.refunded and payment.refund_partial can describe the resulting aggregate payment status. Events in the refund.* family describe the individual refund lifecycle. Make refund processing idempotent using the event identifier and identify the refund by subject.payment.refunds[].token.

Payout event example

Payouts use the payment.* event family. Identify a payout through subject.payment.type; there are no payout.* webhook names.

{
  "source": "SAFEPAY_RAAST",
  "kind": "PAYMENT_EVENT",
  "code": "PAYMENT_SETTLED",
  "version": "V1_0_0",
  "timestamp": "2026-09-14T12:25:40Z",
  "identifier": "txnlog_d55ccbd4-f770-4228-869c-adc3afe31dc7",
  "partnerId": "partner_12345678-1234-1234-1234-123456789012",
  "aggregatorId": "agg_2288490a-2176-4de5-b373-0ffb6f8e2e6e",
  "subject": {
    "payment": {
      "token": "pm_eea10c61-0b79-44c9-b218-57f14692da41",
      "aggregatorId": "agg_2288490a-2176-4de5-b373-0ffb6f8e2e6e",
      "aggregatorMerchantId": "",
      "orderId": "payout-7781",
      "type": "PAYOUT",
      "amount": "500000",
      "status": "P_SETTLED",
      "requestId": "8b76454c-30b0-412f-98b2-da72df9c0f9c",
      "traceReference": "payout-trace-7781"
    }
  },
  "destinations": [],
  "raastChannel": "",
  "webhookEventType": "payment.settled"
}

Failed events

For payment.failed, payment.rejected, or refund.failed, use the resource snapshot and its transaction logs to determine the latest known state. Do not confuse a business failure inside the event with last_error from the Webhook Delivery API: last_error describes Safepay’s HTTP delivery attempt, such as status 422, not why the payment or refund failed.

Match headers to the body

Before processing, verify that the routing headers agree with the signed body:

Header	Body field
X-SFPY-EVENT-ID	identifier
X-SFPY-EVENT-TYPE	webhookEventType
X-SFPY-AGGREGATOR-ID	aggregatorId

The HMAC covers the body, not these routing headers individually. Verify the body signature first, then reject the request if a routing header does not match its signed body field or your expected aggregator and subscription.

See also

• Webhooks delivery
• Webhooks concept
• Payment lifecycle
• Refunds
• Find Webhook Delivery