> ## Documentation Index
> Fetch the complete documentation index at: https://razorpay.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# DuitNow QR

> Steps to integrate S2S JSON API and accept payments using DuitNow QR.

Available in
🇲🇾 Malaysia

[DuitNow QR](https://razorpay.com/docs/my/payments/payment-methods/duitnow/qr.md) lets your customers pay by scanning a QR code with any Malaysian banking or e-wallet app. With the S2S integration, your server creates the payment and receives the QR data. You then show the QR in your own interface, such as a web page, kiosk or app screen.

## Prerequisites

* S2S integration and DuitNow QR are enabled on your account. Razorpay Curlec does not enable S2S by default. Raise a request with our [Support team](https://curlec.com/support/) to enable both.
* You have live [API keys](https://razorpay.com/docs/my/payments/dashboard/account-settings/api-keys.md#generate-api-keys). DuitNow QR is not available in test mode. Test with a live RM 1 payment and refund it.
* You have [set up webhooks](https://razorpay.com/docs/my/webhooks/setup-edit-payments.md) for `payment.captured` and `payment.failed` (recommended).

## Integration Steps

Follow the steps below to integrate the Razorpay Curlec S2S JSON API and accept payments using DuitNow QR.

**1.1** [Create an Order](#1-1-create-an-order)

**1.2** [Create a Payment](#1-2-create-a-payment)

**1.3** [Display the QR Code](#1-3-display-the-qr-code)

**1.4** [Track the Payment Status](#1-4-track-the-payment-status)

**1.5** [Fetch Payment Details and Verify Payment Status](#1-5-fetch-payment-details-and-verify-payment-status)

### 1.1 Create an Order

To process a payment, create a Razorpay Curlec Order to correspond with the order in your system. Create an order in MYR for every payment. The amount is in sen: minimum `100` (RM 1.00), maximum `5000000` (RM 50,000).

**Order is an important step in the payment process.**

* An order should be created for every payment.
* You can create an order using the [Orders API](#api-sample-code). It is a server-side API call. Know how to [authenticate](https://razorpay.com/docs/my/payments/dashboard/account-settings/api-keys.md#generate-api-keys) Orders API.
* The `order_id` received in the response should be passed in the payment request. This ties the order with the payment and secures the request from being tampered.

> [!WARNING]
>
> **Watch Out!**
>
> Payments made without an `order_id` cannot be captured and will be automatically refunded. You must create an order before initiating payments to ensure proper payment processing.

#### API Sample Code

Use this endpoint to create an order using the Orders API.

`POST /orders`

```bash Curl theme={null}
curl -u [YOUR_KEY_ID]:[YOUR_KEY_SECRET] \
-X POST https://api.razorpay.com/v1/orders \
-H "content-type: application/json" \
-d '{
  "amount": 10000,
  "currency": "MYR",
  "receipt": "receipt#1",
  "notes": {
    "notes_key_1": "Nasi Lemak"
  }
}'
```

```java Java theme={null}
RazorpayClient razorpay = new RazorpayClient("[YOUR_KEY_ID]", "[YOUR_KEY_SECRET]");

JSONObject orderRequest = new JSONObject();
orderRequest.put("amount", 10000); // amount in sen
orderRequest.put("currency", "MYR");
orderRequest.put("receipt", "receipt#1");

Order order = razorpay.orders.create(orderRequest);
```

```python Python theme={null}
import razorpay
client = razorpay.Client(auth=("YOUR_ID", "YOUR_SECRET"))

DATA = {
    "amount": 10000,
    "currency": "MYR",
    "receipt": "receipt#1",
    "notes": {
        "notes_key_1": "Nasi Lemak"
    }
}
client.order.create(data=DATA)
```

```php PHP theme={null}
$api = new Api($key_id, $secret);

$api->order->create(array('receipt' => 'receipt#1', 'amount' => 10000, 'currency' => 'MYR', 'notes' => array('notes_key_1' => 'Nasi Lemak')));
```

```csharp .NET theme={null}
RazorpayClient client = new RazorpayClient("[YOUR_KEY_ID]", "[YOUR_KEY_SECRET]");

Dictionary<string, object> options = new Dictionary<string, object>();
options.Add("amount", 10000); // amount in sen
options.Add("receipt", "receipt#1");
options.Add("currency", "MYR");
Order order = client.Order.Create(options);
```

```ruby Ruby theme={null}
require "razorpay"
Razorpay.setup('YOUR_KEY_ID', 'YOUR_SECRET')

order = Razorpay::Order.create(amount: 10000, currency: 'MYR', receipt: 'receipt#1')
```

```javascript Node.js theme={null}
var instance = new Razorpay({ key_id: 'YOUR_KEY_ID', key_secret: 'YOUR_SECRET' })

instance.orders.create({
  amount: 10000,
  currency: "MYR",
  receipt: "receipt#1",
  notes: {
    notes_key_1: "Nasi Lemak"
  }
})
```

```go Go theme={null}
import ( razorpay "github.com/razorpay/razorpay-go" )
client := razorpay.NewClient("YOUR_KEY_ID", "YOUR_SECRET")

data := map[string]interface{}{
  "amount": 10000,
  "currency": "MYR",
  "receipt": "receipt#1",
}
body, err := client.Order.Create(data, nil)
```

```json Success Response theme={null}
{
  "id": "order_TtoLscGlfFEarT",
  "entity": "order",
  "amount": 10000,
  "amount_paid": 0,
  "amount_due": 10000,
  "currency": "MYR",
  "receipt": "receipt#1",
  "offer_id": null,
  "status": "created",
  "attempts": 0,
  "notes": {
    "notes_key_1": "Nasi Lemak"
  },
  "created_at": 1793295960
}
```

> [accordion] Request Parameters
>
> `amount` *mandatory*
> : `integer` Payment amount in sen. For example, for RM 100.00, enter `10000`. Minimum `100` (RM 1.00), maximum `5000000` (RM 50,000).
>
> `currency` *mandatory*
> : `string` Must be `MYR`.
>
> `receipt` *optional*
> : `string` Your receipt id for this order. Maximum length is 40 characters.
>
> `notes` *optional*
> : `json object` Key-value pairs to store additional information about the order. Maximum 15 key-value pairs, 256 characters (maximum) each.
>
> Know more about [Orders API](https://razorpay.com/docs/my/api/orders/create.md).

> [accordion] Response Parameters
>
> Descriptions for the response parameters are present in the [Orders Entity](https://razorpay.com/docs/my/api/orders/entity.md) parameters table.

### 1.2 Create a Payment

Once an order is created, create a payment with `duitnow` as the method and `duitnow.flow` as `qr`.

`POST /payments/create/json`

```bash Request theme={null}
curl -u [YOUR_KEY_ID]:[YOUR_KEY_SECRET] \
-X POST https://api.razorpay.com/v1/payments/create/json \
-H "content-type: application/json" \
-d '{
  "amount": 10000,
  "currency": "MYR",
  "order_id": "order_TtoLscGlfFEarT",
  "email": "nur.aisyah@example.com",
  "contact": "+60123456789",
  "method": "duitnow",
  "duitnow": {
    "flow": "qr"
  },
  "authentication": {
    "authentication_channel": "browser"
  },
  "browser": {
    "java_enabled": false,
    "javascript_enabled": true,
    "timezone_offset": -480,
    "color_depth": 24,
    "screen_width": 1920,
    "screen_height": 1080
  },
  "ip": "105.106.107.108",
  "referer": "https://merchantsite.com/example/paybill",
  "user_agent": "Mozilla/5.0"
}'
```

```json Response theme={null}
{
  "razorpay_payment_id": "pay_TtoMVFSejp8rLM",
  "next": [
    {
      "action": "qr",
      "qr": {
        "image_content": "00020201021226460014A000000615000101068901600214...6304XXXX",
        "expires_at": 1793296574
      }
    },
    {
      "action": "poll",
      "url": "https://api.razorpay.com/v1/payments/pay_TtoMVFSejp8rLM"
    }
  ]
}
```

> [!WARNING]
>
> **Watch Out!**
>
> Do not send `callback_url`. Razorpay Curlec does not redirect the customer or call the `callback_url` for DuitNow QR. Track the payment status with webhooks or by polling, as explained in [step 1.4](#1-4-track-the-payment-status).

#### Request Parameters

`amount` *mandatory*
: `integer` Amount in sen. Must match the order amount. Minimum `100` (RM 1.00), maximum `5000000` (RM 50,000).

`currency` *mandatory*
: `string` Must be `MYR`.

`order_id` *mandatory*
: `string` The order ID from [step 1.1](#1-1-create-an-order).

`email` *mandatory*
: `string` Customer's email address.

`contact` *mandatory*
: `string` Customer's phone number with country code. For example, `+60123456789`.

`method` *mandatory*
: `string` Must be `duitnow`.

`duitnow` *mandatory*
: `object` DuitNow details.

`flow` *mandatory*
: `string` Must be `qr`.

`ip` *mandatory*
: `string` Customer's IP address.

`referer` *optional*
: `string` Referrer header passed by the customer's browser.

`user_agent` *optional*
: `string` Customer's browser user agent.

`authentication` *optional*
: `object` Details of the authentication channel. Same as other [S2S payments](https://razorpay.com/docs/my/payments/payment-gateway/s2s-integration/payment-methods.md). We recommend you send it.

`browser` *optional*
: `object` Information about the customer's browser. Same as other [S2S payments](https://razorpay.com/docs/my/payments/payment-gateway/s2s-integration/payment-methods.md). We recommend you send it. Take the values from the customer's browser; the values in the sample are only examples.

`notes` *optional*
: `object` Key-value pairs to store additional information. Maximum 15 key-value pairs.

#### Response Parameters

`razorpay_payment_id`
: `string` Unique identifier of the payment. Store it to track the payment.

`next`
: `array` Two action objects: `qr` and `poll`.

`action`
: `string` The next step available to you. Possible values:

* `qr`: The QR to show to the customer.
* `poll`: The URL to check the payment status.

`qr`
: `object` Present when `action` is `qr`.

`image_content`
: `string` The DuitNow QR string. It already contains the amount, currency, your business name and the payment reference. Encode it as a QR image with any standard QR library. It is not a URL and not an image.

`expires_at`
: `integer` Unix timestamp when the QR expires, 10 minutes after the payment is created. Use it for your countdown.

`url`
: `string` Present when `action` is `poll`. Call it from your server with your API keys. It returns the [payment entity](https://razorpay.com/docs/my/api/payments/entity.md).

### 1.3 Display the QR Code

PayNet requires every DuitNow QR shown on a screen to follow the DuitNow QR brand guidelines. Download the DuitNow QR logo, the brand guidelines and the approved digital display templates from PayNet's [DuitNow QR Branding & Guidelines](https://docs.developer.paynet.my/docs/duitNow-QR/introduction/branding-&-guidelines) page.

Your QR display must have these four items:

1. The DuitNow QR logo: the DuitNow logo with the label **QR** below it.
2. The QR code, encoded from `image_content`.
3. Your business name, in capital letters.
4. The tagline **MALAYSIA NATIONAL QR**.

You can also add "Accepted by participating Banks and e-Wallets" and the logos of banks and e-wallets, such as Maybank, CIMB and Touch 'n Go eWallet.

#### Build the QR Frame

| Element | Rule |
| - | - |
| Frame | Place the QR code inside a ruby frame (`#ED2E67`). Measure in equal units: 4 units of white space around the QR code, then 2 units of ruby frame around that. |
| Tagline | Make the bottom of the frame 6 units tall. Centre **MALAYSIA NATIONAL QR** in it, 2 units tall, in capitals. |
| Typeface | Gotham Rounded Bold, or Calibri Bold if Gotham Rounded is not available. Use capitals for the tagline and your business name. |
| Logo size | The DuitNow QR logo must be at least 42 px tall on screen, with clear space around it. |
| Colour | Show the display in full colour. Use the black or white version only if the screen cannot show colour. |
| Scaling | Scale the whole display in proportion to the screen. Do not change the ratio between the QR code, the white space and the frame. |

For an example of a compliant display, see the digital display templates on PayNet's [DuitNow QR Branding & Guidelines](https://docs.developer.paynet.my/docs/duitNow-QR/introduction/branding-&-guidelines) page. For brand questions, contact our [Support team](https://curlec.com/support/).

> [!WARNING]
>
> **Watch Out!**
>
> * Do not stretch, crop, rotate, recolour or add effects to the DuitNow QR logo. Do not separate DuitNow from the QR label.
> * Do not place text, buttons or images over the QR code or inside its white space.
> * Write the name as DuitNow QR, not Duitnow, DuitNow Qr or DNQR.

#### Show the QR

* Encode `image_content` as a QR code at least 200 × 200 px, inside the frame above. Show the amount next to the display.
* Show a countdown to `expires_at`. When it reaches zero, stop showing the QR.
* To offer a new QR, create a new order and a new payment. A payment cannot be reused.
* On mobile, let the customer save the QR as an image so they can pay from their banking or e-wallet app on the same phone.

The sample below turns `image_content` into a QR image with the `qrcode` library in Node.js:

```javascript Node.js theme={null}
const QRCode = require("qrcode");

const qr = payment.next.find(n => n.action === "qr").qr;
const dataUrl = await QRCode.toDataURL(qr.image_content, { width: 256, margin: 0 });
// place dataUrl inside the DuitNow QR frame, with a countdown to qr.expires_at
```

### 1.4 Track the Payment Status

There is no redirect and no callback for DuitNow QR, so use one or both of these:

* **Webhooks (recommended)**: Subscribe to `payment.captured` and `payment.failed`. You also receive `payment.authorized` and `order.paid`. [Validate the `X-Razorpay-Signature` header](https://razorpay.com/docs/my/webhooks/validate-test#validate-webhooks) on each webhook. The same event can be delivered more than once, so fulfil each order only once, for example by checking the payment ID before you fulfil.
* **Polling**: While the QR is on screen, call the `poll` URL from your server every 3 to 5 seconds. Stop when `status` is `captured` or `failed`, or when the QR expires. If a poll returns `429` or a `5xx` error, wait longer before the next call instead of stopping.

If the customer does not pay before `expires_at`, the payment fails with the error code `BAD_REQUEST_PAYMENT_TIMED_OUT` and you receive `payment.failed`.

#### Request Errors

| When | What to do |
| - | - |
| DuitNow is not enabled on your account | Ask Razorpay Curlec to enable DuitNow QR. |
| `duitnow.flow` is missing or not `qr` | Send `duitnow.flow` as `qr`. |
| Currency is not MYR | Create the order and payment in MYR. |
| Amount is below RM 1.00 or above RM 50,000 | Use an amount within the limits. |

### 1.5 Fetch Payment Details and Verify Payment Status

Fetch the payment with your API keys before you fulfil the order:

```bash Request theme={null}
curl -u [YOUR_KEY_ID]:[YOUR_KEY_SECRET] \
-X GET https://api.razorpay.com/v1/payments/pay_TtoMVFSejp8rLM
```

```json Response theme={null}
{
  "id": "pay_TtoMVFSejp8rLM",
  "entity": "payment",
  "amount": 10000,
  "currency": "MYR",
  "status": "captured",
  "order_id": "order_TtoLscGlfFEarT",
  "method": "duitnow",
  "duitnow": {
    "flow": "qr"
  },
  "captured": true,
  "amount_refunded": 0,
  "refund_status": null,
  "international": false,
  "bank": null,
  "wallet": null,
  "vpa": null,
  "email": "nur.aisyah@example.com",
  "contact": "+60123456789",
  "fee": 0,
  "tax": 0,
  "error_code": null,
  "error_description": null,
  "acquirer_data": {},
  "notes": [],
  "created_at": 1793295974
}
```

Fulfil the order only when `status` is `captured` and the `amount` and `order_id` match.

> [!NOTE]
>
> **Handy Tips**
>
> On the Razorpay Curlec Dashboard, ensure that the payment status is `captured`. Refer to the payment capture settings page to know how to [capture payments automatically](https://razorpay.com/docs/my/payments/payments/capture-settings.md).

## Refunds

You can refund a DuitNow QR payment in full or in part, the same as any other payment, using the [Refunds API](https://razorpay.com/docs/my/api/refunds/create-normal.md) (`POST /v1/payments/{id}/refund`). Refunds are processed within 3 to 5 working days.

## Frequently Asked Questions (FAQs)

> [accordion] 1. Do I get a QR image or a link?
>
> Neither. You get the QR string in `image_content` and encode it as a QR image yourself.

> [accordion] 2. How long is the QR valid?
>
> 10 minutes from payment creation. The exact time is in `expires_at`.

> [accordion] 3. Will my callback\_url be called?
>
> No. Track the status with webhooks or by polling the payment.

> [accordion] 4. Can I show the same QR again for a retry?
>
> No. Create a new order and a new payment for each QR.

> [accordion] 5. Can I test in test mode?
>
> No. Make a live RM 1 payment and refund it.

> [accordion] 6. Do I need PCI-DSS certification?
>
> No. DuitNow QR does not involve card data.

> [accordion] 7. Do I have to follow PayNet's brand guidelines?
>
> Yes. Any DuitNow QR you show must use the DuitNow QR logo, the ruby frame and the **MALAYSIA NATIONAL QR** tagline. See PayNet's [DuitNow QR Branding & Guidelines](https://docs.developer.paynet.my/docs/duitNow-QR/introduction/branding-&-guidelines) page.

## Next Steps

DuitNow QR is not available in test mode, so skip Step 2: Test Integration for this method. Make a live RM 1 payment and refund it, then complete the [Go-live Checklist](https://razorpay.com/docs/my/payments/payment-gateway/s2s-integration/json/v2/go-live-checklist.md).

### Related Information

* [DuitNow QR](https://razorpay.com/docs/my/payments/payment-methods/duitnow/qr.md)
* [S2S Payment Methods](https://razorpay.com/docs/my/payments/payment-gateway/s2s-integration/payment-methods.md)
* [Refunds](https://razorpay.com/docs/my/payments/refunds/normal.md)
