Callback Notifications

Smilepayz sends HTTP POST notifications to your server when a pay-in or withdrawal order reaches a final status. This guide covers callback URL setup, sandbox testing, signature verification, and how to respond.

Overview

Callbacks let your system:

• Receive asynchronous pay-in and withdrawal status updates
• Confirm order outcomes without polling the inquiry API
• Update your internal order state after verifying the signature

API orders only

Callbacks are sent only for orders created through the Pay-in / Pay-out API. Orders created from Payment Links in the merchant backend cannot be linked back to your integration.

Prerequisites

Before handling callbacks, ensure you have:

• A publicly reachable callback URL (http:// or https://; HTTPS on port 443 is recommended)
• The Platform Public Key from sandbox or production Integration Information
• Server-side logic to verify signatures and return SUCCESS

Configure Callback URLs

Sandbox

1. Sign in to the merchant backend.
2. Switch the top toggle to Sandbox.
3. Open Configuration → API Setting.
4. Under API Notify Address, set:
   • Payin — URL for pay-in completion notifications
   • Withdraw — URL for withdrawal completion notifications
5. Click Save.

Retries and idempotency

The backend may retry failed callbacks. Your endpoint should verify the signature on every request and handle duplicate notifications idempotently (same tradeNo / orderNo should not be processed twice).

For production URLs and IP whitelist setup, see Integration Information.

Sandbox Testing

In sandbox you can trigger a test callback from the order list after creating an API order.

Step 1: Create a sandbox API order

Create a pay-in order through the API (see your region’s Pay-in reference). The request must include a non-empty paymentMethod (for example QRIS for Indonesia).

Step 2: Simulate a callback

1. In the merchant backend (Sandbox), go to Pay-in Order.
2. Search for the order you created.
3. In the Operate column, click Set Callback to simulate a success or failure notification.
4. Check the Callback Status column for delivery result.

Payment method required

If paymentMethod is empty when you create the sandbox order, Set Callback may not work as expected. Always pass a valid payment method in the API request.

Production

When a real payment or disbursement completes, Smilepayz sends the callback automatically. No manual Set Callback action is available.

Verify Callback Signatures

Each callback includes signature headers. Verify them with the Platform Public Key before updating your order.

Request headers

Header	Description
Content-Type	application/json
X-TIMESTAMP	Timestamp, e.g. 2020-12-17T10:55:00+07:00
X-SIGNATURE	RSA signature (Base64)

String to sign

Smilepayz signs with its platform private key. You verify with the platform public key:

stringToSign = tradeNo + "|" + X-TIMESTAMP
X-SIGNATURE = SHA256withRSA(smilepayz_private_key, stringToSign)

Verification steps

1. Read X-SIGNATURE and X-TIMESTAMP from the request headers.
2. Read tradeNo from the JSON body.
3. Build stringToSign as tradeNo + "|" + X-TIMESTAMP.
4. Verify X-SIGNATURE with the Platform Public Key using SHA256withRSA.
5. If valid, process the status update; otherwise reject the request.

Use checkSha256RsaSignature from the Tools / SDK documentation, or see Signature Authorization for the full signing model.

Callback Body (JSON)

The callback POST body is JSON. Key fields include orderNo, tradeNo, merchantId, status, money, and transactionTime.

transactionTime format: yyyy-MM-ddTHH:mm:ss (timezone of the region where the order was created).

For the full field list, see Notification / Callback → Body Parameters in your region’s Pay-in or Pay-out API reference.

Respond to Callbacks

After successful verification and processing, return the plain text string:

SUCCESS

Do not return JSON or other content. Smilepayz treats any other response as a failed delivery and may retry.

Implementation Checklist

1. Configure URLs — Set pay-in and withdrawal notify addresses in sandbox/production.
2. Get Platform Public Key — From Integration Information.
3. Verify every callback — Check X-SIGNATURE before trusting the body.
4. Update order state — Map status to your internal workflow.
5. Return SUCCESS — Only after your side has safely recorded the update.

Important Notes

• Always verify signatures — Never trust an unverified callback body.
• Use the correct public key — Sandbox and production keys differ.
• Idempotent handling — Retries may deliver the same notification more than once.
• API orders only — Payment-link orders in the merchant portal do not trigger integration callbacks.

Troubleshooting

Issue	What to do
No callback received	Confirm the notify URL is saved; check firewall and HTTPS certificate
Signature verification fails	Use the Platform Public Key for the same environment; check tradeNo and X-TIMESTAMP order in stringToSign
Sandbox Set Callback missing	Create the order via API first; ensure paymentMethod is not empty
Callback keeps retrying	Return plain text SUCCESS with HTTP 200 after processing

Support

• Documentation: Regional API references and Signature Authorization
• Technical Support: Callback URL and signature issues
• Customer Service: Account and environment access