List of order input attributes

Below is a complete list of attributes that you may use in the creation of an order to further enhance the experience for you and your customers.

Standard order data attributes

What follows is a list of common/standard data attributes used by the N-Genius Online payments APIs.
Marked as * are mandatory fields to complete the integration.
Marked ** are mandatory to complete your KYC process.

Attribute

Example

Comments

*action

"AUTH", "SALE", "PURCHASE"

Order type

*amount { }

N/A

Amount block

*amount.currencyCode

"AED", "USD", "EUR"

Order currency

*amount.value

1000 (minor units)

Order amount

*emailAddress

[email protected]

Payer's email address

language

"en", "ar", "fr"

Language switch (English, Arabic and French available)

merchantAttributes { }

N/A

merchantAttributes block

merchantAttributes.redirectUrl

https://mysite.com/redirect

URL to redirect card-holder to after payment

merchantAttributes.skipConfirmationPage

true (to skip), false

Indicates whether the customer will be presented with a payment confirmation page before being redirected back to your site.

merchantAttributes.skip3DS

true (to skip), false

Indicates whether the customer will be taken to the relevant 3D-Secure program for authentication.

merchantAttributes.cancelUrl

https://myshop.com/basket

URL to redirect card-holder to, in the event they want to return to shop before completing the payment

merchantAttributes.cancelText

Default 'Continue Shopping'
Example 'Return to Basket'

The text you want to display on the pay-page to return a card-holder to your website.

merchantOrderReference

myorder-00001

Your own, optional reference. Accepted format allows alphanumeric characters (Aa-Zz and 0-9), and hyphens (-) only.

billingAddress { }

N/A

billingAddress block

*billingAddress.firstName

Test

Billing address first name

*billingAddress.lastName

Customer

Billing address last name

**billingAddress.address1

123 Test Street

Billing address

**billingAddress.city

Dubai

Billing address city

**billingAddress.countryCode

UAE

Billing address country

shippingAddress { }

N/A

shippingAddress block

shippingAddress.firstName

Test

Shipping address first name

shippingAddress.lastName

Customer

Shipping address last name

shippingAddress.address1

123 Test Street

Shipping address

shippingAddress.city

Dubai

Shipping address city

shippingAddress.countryCode

UAE

Shipping address country

Further information on key/optional data blocks, per your N-Genius Online account configuration can be found below:

Merchant defined data fields

Merchants may specify up to 100 custom data fields in a dedicated JSON block called merchantDefinedData. In all cases, both the key and value of these key/value pairs is entirely controlled by you, and will be reflected on the N-Genius Online portal (in the Order Details) page, and in any order reports you download.

Key

Value (Example)

Description

merchantDefinedData { }

N/A

Merchant defined data block

merchantDefinedData.[key]

shopperId

Shopper ID

merchantDefinedData.[key]

orderId

Internal order reference

This block will also be returned in any query (GET) against the status of the order, in any web-hooks that you define, and in any synchronous responses provided by the N-Genius Online APIs.

Token (savedCard) data fields

Tokens allow you to develop more seamless user experiences by saving the returned token data to your systems (as an alias for the card information itself) so that they may be represented either to the hosted payment page, or any API end-point where raw card-data might otherwise be passed.

If your N-Genius Online account is enabled for the Pay-by-Token facility, every time a card is presented by you or your customer to the N-Genius Online gateway, a 'savedCard' block will be returned.

From this point on, you may then present this data back to the relevant payment API instead of the raw card information, thereby supporting a more personalized customer journey at the point of sale, whilst also avoiding additional PCI DSS risk.

Attribute

Example

Description

savedCard { }

N/A

savedCard block

savedCard.cardToken

[Base64 string]

PAN alias (token) of payment card

savedCard.cardholderName

Test Customer

Payer name

savedCard.expiry

2025-04

Card expiry date

savedCard.maskedPan

401200**1112

BIN and last 4 digits of the payment card

savedCard.scheme

VISA, MASTERCARD, AMERICAN_EXPRESS, DINERS_CLUB_INTERNATIONAL

Scheme/network of the payment card.

savedCard.cvv

123

Only supported for input, not returned in response.

recaptureCsc

true / false

This flag will dictate whether the payment card's security code (3/4 digits) needs to be recaptured on the pay-page.

Note: the maskedPan, scheme and recaptureCsc fields are only required in Payment Page integrations

Payment facilitator (PayFac) data fields

A payment-facilitator (sometimes called 'merchant aggregator') integration type is one where a merchant will submit payments for authorization on behalf of a sub-merchant.

Common examples of this include instances where a Payment Service Provider (PSP) or a super-ordinate business is entrusted with the payment acceptance operation for a sub-ordinate legal entity or subsidiary.

Attribute

Example

Description

payFacData

N/A

Data block for payment facilitator information

payFacData.payFacId

1234567890

The identifier provided to you, as a payment facilitator, when registered with the schemes. Note that this value will likely be different per scheme.

payFacData.saleOrgId

0987654321

Identifier for the sub-merchant as registered with the schemes

dynamicDescriptor

N/A

Dynamic descriptor block

dynamicDescriptor.merchantName

PYF MyMerchant

Three character code denominating the name of the Payment Facilitator, followed by a space, then the name of the merchant.

dynamicDescriptor.merchantAddress

N/A

Registered merchant address datablock

...merchantAddress.city

Dubai

Registered merchant city

...merchantAddress.state

Dubai

Registered merchant state

...merchantAddress.country

AE

Registered merchant country

🚧

Payment Facilitators

Please note that these input fields are provided for businesses legally registered as payment facilitators or master merchants, and should not be used otherwise. Please contact your nominated support team for further information if you are unsure how to obtain the information required, or whether they will be required for your gateway integration.

Example (JSON):

"order": {
  
  "payFacData": {
  
    "payFacId":"1234567890",
    "saleOrgId":"0987654321"
  
  },
  "dynamicDescriptor": {
  
    "merchantName":"PYF MyMerchant",
        "merchantAddress": {
    
        "city":"Dubai",
        "state":"Dubai",
        "country":"AED"
    
    }    
  
  }
  
}

MO/TO (Mail Order, Telephone Order) payments

Where your N-Genius Online account is configured to support such payments, you may also pass an additional flag (detailed below) to the payments APIs to indicate that the payment should use the MO/TO processing channel.

The MO/TO processing channel is intended for merchants who process payments in a Card-Not-Present (CNP) environment, and whose customers do not directly control the payment journey, and cannot therefore undertake a card-holder authentication challenge (such as 3-D Secure).

Examples of such environments may include:

  • Call-centers, whose agents accept payments over the telephone by keying in the card-information provided to them by their customers.
  • IVR systems, wherein customers are keying in their payment information to a DTMF or similar system, but are not therefore presented with a 3-D Secure challenge.

In order to indicate that a payment should use the MO/TO processing channel (and therefore avoid any 3-D Secure challenge that might otherwise be required), please pass the following flag to your N-Genius Online APIs in the order creation step:

Key

Value

channel

'MoTo'

🚧

MO/TO payments

Payments taken in a MO/TO environment, or via a MO/TO processing channel, are inherently a less secure form of transaction. As a result, not only may your ability to process transactions of this type be restricted by N-Genius Online, you may also incur higher costs for processing these transactions from your acquirer.