Skip to main content

Payment Mocking Sandbox Guide

This guide walks you through the process of mocking a payment flow using the Sandbox API and our Payment Listener.

1. Initiate the Payment Session​

To begin mocking a payment, you must first create a payment session via the backend API. This is typically done externally (e.g., from your own backend application or manually via a tool like Postman or curl).

Make a POST request to the sandbox initiate endpoint. Make sure to replace the placeholder values below with your actual credentials, IDs, and URLs.

Example Request​

curl --location 'https://paymentgateway.dev.digieconcenter.gov.lk/IPG/v2.0.0/api/sandbox/initiate' \
--header 'accept: application/json' \
--header 'X-DIS-CLIENT-ID: YOUR_CLIENT_ID_HERE' \
--header 'Content-Type: application/json' \
--data-raw '{
  "merchant_id": "YOUR_MERCHANT_ID",
  "amount": 3567.00,
  "currency": "LKR",
  "notify_url": "https://api.yourdomain.com/v1/payments/webhook",
  "return_url": "YOUR_RETURN_URL",
  "metadata": {
    "first_name": "John",
    "last_name": "Doe",
    "email": "john.doe@example.com"
  }
}'

Example Response​

If successful, the API will respond with a payment session confirmation. It will contain a redirect_url which points to the mock frontend simulator.

{
    "status": "success",
    "message": "Payment session created.",
    "data": {
        "transaction_id": "txn-fe103b9b-dd08-40cf-8c69-7d25135e74c9",
        "redirect_url": "http://localhost:5175/api/sandbox/checkout/txn-fe103b9b-dd08-40cf-8c69-7d25135e74c9?clientId=YOUR_CLIENT_ID_HERE"
    }
}

2. Simulate the Payment​

Open the redirect_url from the response above. (Or redirect the user to that URL)

You will be presented with a simulated payment gateway interface. (You can change the outcome of the transaction from the frontend simulator)

3. Handle Webhook Notifications​

When the simulated payment finishes (either successfully or if it gets canceled), the gateway will send a POST request containing the final transaction payload to the notify_url you specified during initiation. This URL should be an endpoint on your own server designed to receive and process these updates (e.g., https://api.yourdomain.com/v1/payments/webhook).

Below are examples of the JSON payloads you can expect your webhook endpoint to receive.

Example: Payment Success Payload​

{
  "transaction_id": "txn-fe103b9b-dd08-40cf-8c69-7d25135e74c9",
  "merchant_id": "YOUR_MERCHANT_ID",
  "amount": 3567.00,
  "currency": "LKR",
  "status": "SUCCESS",
  "timestamp": "2026-07-03T15:00:00Z",
  "metadata": {
    "first_name": "John",
    "last_name": "Doe",
    "email": "john.doe@example.com"
  }
}

Example: Payment Cancellation Payload​

{
  "transaction_id": "txn-fe103b9b-dd08-40cf-8c69-7d25135e74c9",
  "merchant_id": "YOUR_MERCHANT_ID",
  "amount": 3567.00,
  "currency": "LKR",
  "status": "CANCELED",
  "timestamp": "2026-07-03T15:02:00Z",
  "metadata": {
    "first_name": "John",
    "last_name": "Doe",
    "email": "john.doe@example.com"
  }
}