Skip to main content

Direct Implementation

NomuPay transactions require you to redirect your Customer’s browser to the appropriate NomuPay APM Checkout as part of the transaction flow. The transaction must be done in two stages with the Checkout being displayed between the stages.

NomuPay APM’s support payments made using the SALE action, and the majority support the refunds and partial refunds using the REFUND_SALE action. This section explains how to make payment requests. Refund requests are performed as detailed in the Management Requests section.

Some NomuPay APMs may require further payment data which you may send using the checkoutOptions field in your initial request as detailed in the NomuPay Checkout Options (Hosted and Direct) section.

Additional information available from a NomuPay APM Checkout may be made available in the checkoutDetails and acquirerResponseDetails response fields.

The direct integration uses two complex fields to pass data between the NomuPay APM Checkout and the Gateway, the checkoutRequest and checkoutResponse fields.

The checkoutRequest field will optionally be provided by the Gateway and is a record whose name/value properties must be sent to the Checkout, at the provided checkoutURL, via a HTTP POST request. If not provided, then the Checkout can be opened using a normal HTTP GET request.

The corresponding checkoutResponse field will be returned by the Gateway and is a record containing name/value properties received from the Checkout when it redirects the Cardholder’s browser back to the URL provided using the checkoutRedirectURL on completion.

The contents of the checkoutOptions, checkoutDetails, checkoutRequest, checkoutResponse and acquirerResponseDetails fields are formatted using the record format, the checkoutOptions field also supports being provided using the serialised record format.

Payment Request​

To request that a transaction be processed via NomuPay the request must contain a paymentMethod of ‘nomupay.xxxx’, where ‘xxxx’ is the NomuPay APM tag listed in the Payment Method Tags section below.

The request must also have a checkoutRedirectURL containing the URL of a page on your server to return to when the Checkout is closed. In addition, you may send checkoutOptions to provide further custom fields required by the APM as detailed in the NomuPay Checkout Options (Hosted and Direct) section.

When the Gateway receives these fields, assuming there are no other errors with the request, it will attempt to find a suitable NomuPay Merchant Account in the current account mapping group (Refer to the Merchant Account Routing section).

If the Gateway is unable to find a suitable account, then the transaction will be aborted, and it will respond with a responseCode of 66364 (INVALID PAYMENTMETHOD).

Otherwise, the Gateway will respond with a responseCode of 65826 (CHECKOUT REQUIRED) and included in the response will be a checkoutURL field containing the URL of a NomuPay APM Checkout that your Customer’s browser should be redirected to so that the payment may be completed. The response will also contain a unique checkoutRef which is used by the Gateway to identify this checkout session.

On completion of the NomuPay APM Checkout it will redirect the browser to the checkoutRedirectURL you provided, complete with information about the payment in a HTTP POST request. The posted data will contain a checkoutResponse field that will contain any specific response data for the payment method.

Payment Specific Fields​

Most of the information required by the NomuPay APM Checkout can be supplied using the standard Gateway request fields. However, there may be specific mandatory fields required by a payment method which are not available using the standard fields. In these cases, these fields can be sent in the checkoutOptions data, the value of which must be formatted using the record or serialised record formats.

These fields are listed in the payment method tags table and then detailed in the NomuPay Checkout Options (Hosted and Direct) section.

Customer support will be able to guide you on any mandatory options as you will find the transaction will fail with a responseCode of 65550 (PROCESSOR_ERROR - Invalid request data) if any are missing.

Payment Method Tags​

To specify which APM is required you need to send the paymentMethod field with a value using the format is ‘nomupay.xxxx_’_, where ‘xxxx’ is the alternative payment method’s tag.

For example, to use the alternative payment method Maya that has a tag of “maya” (all lowercase), the resulting payment method code would be “nomupay.maya”.

The table below provides the payment methods available, along with their tags, available countries, currencies, refund/recurring capabilities and checkout option fields.

APM NameAPM TagCountriesCurrenciesRefundsRecurringCheckout Options
7-Elevenseven_elevenMYMYRemail[1]1
BoostboostMYMYRYesemail
DuitNow OnlineduitnowMYMYRYescode
DuitNow QRduitnow_qrMYMYRYes
ECPayecpayPHPHPYes
FPXfpxMYMYRYesYescode
GCashgcashPHPHPYes
GrabPaygrabpayMY,PHMYR,PHPYes
MayamayaPHPHPYes
ShopeePayshopeepayMYMYRYes
TouchAndGotouch_n_goMYMYRYes
Union Payupop_securepayHKHKDYes

[2] The consumer phone number must be provided as it is used to obtain an OTP in the authentication process.

Footnotes​

  1. The consumer email must be provided as it is used to send the 7-Eleven reference. ↩