Notification

After a SoftPOS transaction completes, 2C2P sends a backend notification to your server. This notification delivers the authoritative transaction result and is the recommended source of truth for updating your order and ledger systems.

Notifications apply to all SoftPOS integration modes that involve a merchant backend: Mobile SDK, Device-to-App, and App-to-App. Standalone App mode does not send backend notifications.

How it works

%%{init: {'theme': 'base', 'themeVariables': {'actorBkg': '#e8ecf2', 'actorTextColor': '#00112c', 'actorBorderColor': '#004f5c', 'signalColor': '#0088FF', 'signalTextColor': '#333333', 'activationBkgColor': '#dff0f2', 'activationBorderColor': '#004f5c', 'noteBkgColor': '#f2f2f2', 'noteTextColor': '#00112c', 'noteBorderColor': '#004f5c'}}}%%
sequenceDiagram
    participant POS as SoftPOS
    participant PGW as 2C2P PGW
    participant Backend as Your Server

    POS->>PGW: Process transaction
    activate PGW
    PGW-->>POS: Synchronous result
    deactivate PGW
    PGW->>Backend: POST /your-notification-endpoint
    activate Backend
    Note over Backend: 1. Verify JWT signature<br/>2. Decode payload<br/>3. Match by invoiceNo<br/>4. Update order status
    Backend-->>PGW: HTTP 200 OK
    deactivate Backend

1. A transaction completes on the SoftPOS device.
2. 2C2P sends an HTTP POST to your pre-configured notification endpoint.
3. Your server verifies the JWT signature, decodes the payload, and updates the order status.
4. Your server responds with HTTP 200 to acknowledge receipt.

Endpoint requirements

You must provide 2C2P with a notification endpoint URL during onboarding. The endpoint must meet the following requirements:

Notification structure

Each notification is a JSON object with the following envelope fields:

Payload fields (decoded JWT)

The payload field is a signed JWT. After verifying the signature and decoding the claims, the payload matches the v4 Inquiry API response structure.

Event types

The notification system uses an event-driven architecture. Route your business logic based on the category and event fields.

Security

JWT signature verification

The payload field is a signed JWT. Before processing any notification:

1. Verify the JWT signature using the shared secret or public key provided during onboarding.
2. Validate the claims — confirm the merchantID matches your merchant ID.
3. Check the version field — handle or reject unknown versions as appropriate.

Never trust a notification whose JWT signature cannot be verified. An unverified notification may have been tampered with in transit.

Handling the notification

Recommended processing flow

1. Receive — Accept the POST request and read the JSON body.
2. Verify — Validate the JWT signature on payload. Reject if invalid.
3. Update — Update your order management, ledger, or ERP system with the transaction result.
4. Respond — Return HTTP 200 OK with an empty body.

// Successful response — your server returns:
HTTP/1.1 200 OK
Content-Type: application/json

{}

Sample notifications

Successful SALE

{
  "category": "PAYMENT",
  "event": "SALE",
  "version": "4.3",
  "payload": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJtZXJjaGFudElEIjoiSlQwNCIsImludm9pY2VObyI6IjI4MDUyMDA3NTkyMSIsImNhcmRObyI6IjQxMTExMVhYWFhYWDExMTEiLCJhbW91bnQiOiIyMzAuODciLCJjdXJyZW5jeUNvZGUiOiJUSEIiLCJ0cmFuUmVmIjoiMjg2ODgyMSIsInJlZmVyZW5jZU5vIjoiMjc4NTcwMyIsImFwcHJvdmFsQ29kZSI6IjUzMTQ4NCIsImVjaSI6IjA1IiwidHJhbnNhY3Rpb25EYXRlVGltZSI6IjIwMjAwNTI4MDgwNTA4IiwicmVzcENvZGUiOiIwMDAwIiwicmVzcERlc2MiOiJTdWNjZXNzIn0.QdjSI_dUbiRularwEIFuYROE_svc3Xkm-t58X-VnPxI",
  "invoiceNo": "M1790593277278339073",
  "respCode": "0000",
  "respDesc": "Success"
}

Decoded payload:

{
  "merchantID": "JT04",
  "invoiceNo": "280520075921",
  "cardNo": "411111XXXXXX1111",
  "amount": "230.87",
  "currencyCode": "THB",
  "tranRef": "2868821",
  "referenceNo": "2785703",
  "approvalCode": "531484",
  "eci": "05",
  "transactionDateTime": "20200528080508",
  "respCode": "0000",
  "respDesc": "Success"
}

Failed SALE

{
  "category": "PAYMENT",
  "event": "SALE",
  "version": "4.3",
  "payload": "eyJhbGciOiJIUzI1NiJ9.eyJtZXJjaGFudElEIjoiSlQwNCIsImludm9pY2VObyI6Ik0xNzkwNTkzMjc3Mjc4MzM5MDc0IiwiY2FyZE5vIjoiNDExMTExWFhYWFhYMTExMSIsImFtb3VudCI6IjUwLjAwIiwiY3VycmVuY3lDb2RlIjoiVEhCIiwidHJhblJlZiI6IjI4Njg4MjIiLCJyZWZlcmVuY2VObyI6IjI3ODU3MDQiLCJhcHByb3ZhbENvZGUiOiIiLCJlY2kiOiIiLCJ0cmFuc2FjdGlvbkRhdGVUaW1lIjoiMjAyMDA1MjgwODA1MDgiLCJyZXNwQ29kZSI6IjEwMDEiLCJyZXNwRGVzYyI6IkRlY2xpbmVkIn0.signature",
  "invoiceNo": "M1790593277278339074",
  "respCode": "1001",
  "respDesc": "Declined"
}

Note: For failed transactions, approvalCode and eci are empty strings. Always check respCode before updating your system to a successful state.

VOID

{
  "category": "PAYMENT",
  "event": "VOID",
  "version": "4.3",
  "payload": "eyJhbGciOiJIUzI1NiJ9.eyJtZXJjaGFudElEIjoiSlQwNCIsImludm9pY2VObyI6Ik0xNzkwNTkzMjc3Mjc4MzM5MDc1IiwiaW52b2ljZU5vIjoiTTE3OTA1OTMyNzcyNzgzMzkwNzUiLCJjYXJkTm8iOiI0MTExMTFYWFhYWFgxMTExIiwiYW1vdW50IjoiMTAwLjAwIiwiY3VycmVuY3lDb2RlIjoiVEhCIiwidHJhblJlZiI6IjI4Njg4MjMiLCJyZWZlcmVuY2VObyI6IjI3ODU3MDUiLCJhcHByb3ZhbENvZGUiOiI1MzE0ODUiLCJlY2kiOiIwNSIsInRyYW5zYWN0aW9uRGF0ZVRpbWUiOiIyMDIwMDUyODA4MDUwOCIsInJlc3BDb2RlIjoiMDAwMCIsInJlc3BEZXNjIjoiVm9pZCBzdWNjZXNzZnVsIn0.signature",
  "invoiceNo": "M1790593277278339075",
  "respCode": "0000",
  "respDesc": "Void successful"
}

Note: VOID and REFUND notifications reference the original transaction. Match these against the original tranRef stored in your system.

Response codes

Common response codes returned in the notification. For the complete list, see Payment Response Codes.

Testing

Use the 2C2P Sandbox environment to test your notification handler before going live.

1. Configure your sandbox notification endpoint URL with the 2C2P integration team.
2. Process test transactions through your SoftPOS integration.
3. Verify that your server receives, verifies, and acknowledges each notification.
4. Test failure scenarios: declined transactions, void, and refund notifications.