Available in🇲🇾 Malaysia
DuitNow QR 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 to enable both.
- You have live 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 for
payment.capturedandpayment.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.2 Create a Payment 1.3 Display the QR Code 1.4 Track the Payment Status 1.5 Fetch Payment Details and Verify Payment Status1.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: minimum100 (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. It is a server-side API call. Know how to authenticate Orders API.
- The
order_idreceived in the response should be passed in the payment request. This ties the order with the payment and secures the request from being tampered.
API Sample Code
Use this endpoint to create an order using the Orders API.POST /orders
Success Response
Request Parameters
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.Response Parameters
Response Parameters
Descriptions for the response parameters are present in the Orders Entity parameters table.
1.2 Create a Payment
Once an order is created, create a payment withduitnow as the method and duitnow.flow as qr.
POST /payments/create/json
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.
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. We recommend you send it.
browser optional
: object Information about the customer’s browser. Same as other S2S payments. 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.
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 page. Your QR display must have these four items:- The DuitNow QR logo: the DuitNow logo with the label QR below it.
- The QR code, encoded from
image_content. - Your business name, in capital letters.
- The tagline MALAYSIA NATIONAL QR.
Build the QR Frame
For an example of a compliant display, see the digital display templates on PayNet’s DuitNow QR Branding & Guidelines page. For brand questions, contact our Support team.
Show the QR
- Encode
image_contentas 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.
image_content into a QR image with the qrcode library in Node.js:
Node.js
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.capturedandpayment.failed. You also receivepayment.authorizedandorder.paid. Validate theX-Razorpay-Signatureheader 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
pollURL from your server every 3 to 5 seconds. Stop whenstatusiscapturedorfailed, or when the QR expires. If a poll returns429or a5xxerror, wait longer before the next call instead of stopping.
expires_at, the payment fails with the error code BAD_REQUEST_PAYMENT_TIMED_OUT and you receive payment.failed.
Request Errors
1.5 Fetch Payment Details and Verify Payment Status
Fetch the payment with your API keys before you fulfil the order:status is captured and the amount and order_id match.
Handy TipsOn 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.Refunds
You can refund a DuitNow QR payment in full or in part, the same as any other payment, using the Refunds API (POST /v1/payments/{id}/refund). Refunds are processed within 3 to 5 working days.
Frequently Asked Questions (FAQs)
1. Do I get a QR image or a link?
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.2. How long is the QR valid?
2. How long is the QR valid?
10 minutes from payment creation. The exact time is in
expires_at.3. Will my callback_url be called?
3. Will my callback_url be called?
No. Track the status with webhooks or by polling the payment.
4. Can I show the same QR again for a retry?
4. Can I show the same QR again for a retry?
No. Create a new order and a new payment for each QR.
5. Can I test in test mode?
5. Can I test in test mode?
No. Make a live RM 1 payment and refund it.
6. Do I need PCI-DSS certification?
6. Do I need PCI-DSS certification?
No. DuitNow QR does not involve card data.
7. Do I have to follow PayNet's brand guidelines?
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 page.