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.

AttributeExampleComments
*action"AUTH", "SALE", "PURCHASE"Order type
*amount { }N/AAmount block
*amount.currencyCode"AED", "USD", "EUR"Order currency
*amount.value1000 (minor units)Order amount
*emailAddress[email protected]Payer's email address
language"en", "ar", "fr"Language switch (English, Arabic and French available)
merchantAttributes { }N/AmerchantAttributes block
merchantAttributes.redirectUrlhttps://mysite.com/redirectURL to redirect card-holder to after payment
merchantAttributes.skipConfirmationPagetrue (to skip), falseIndicates whether the customer will be presented with a payment confirmation page before being redirected back to your site.
merchantAttributes.skip3DStrue (to skip), falseIndicates whether the customer will be taken to the relevant 3D-Secure program for authentication.
merchantAttributes.cancelUrlhttps://myshop.com/basketURL to redirect card-holder to, in the event they want to return to shop before completing the payment
merchantAttributes.cancelTextDefault 'Continue Shopping'
Example 'Return to Basket'
The text you want to display on the pay-page to return a card-holder to your website.
merchantOrderReferencemyorder-00001Your own, optional reference. Accepted format allows alphanumeric characters (Aa-Zz and 0-9), and hyphens (-) only.
paymentAttempts3You can give the customer an option to retry the payment attempt incase of failure. Max value 5.
billingAddress { }N/AbillingAddress block
*billingAddress.firstNameTestBilling address first name
*billingAddress.lastNameCustomerBilling address last name
**billingAddress.address1123 Test StreetBilling address
**billingAddress.cityDubaiBilling address city
**billingAddress.countryCodeUAEBilling address country
shippingAddress { }N/AshippingAddress block
shippingAddress.firstNameTestShipping address first name
shippingAddress.lastNameCustomerShipping address last name
shippingAddress.address1123 Test StreetShipping address
shippingAddress.cityDubaiShipping address city
shippingAddress.countryCodeUAEShipping 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.

KeyValue (Example)Description
merchantDefinedData { }N/AMerchant defined data block
merchantDefinedData.[key]shopperIdShopper ID
merchantDefinedData.[key]orderIdInternal 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.

AttributeExampleDescription
savedCard { }N/AsavedCard block
savedCard.cardToken[Base64 string]PAN alias (token) of payment card
savedCard.cardholderNameTest CustomerPayer name
savedCard.expiry2025-04Card expiry date
savedCard.maskedPan401200**1112BIN and last 4 digits of the payment card
savedCard.schemeVISA, MASTERCARD, AMERICAN_EXPRESS, DINERS_CLUB_INTERNATIONALScheme/network of the payment card.
savedCard.cvv123Only supported for input, not returned in response.
recaptureCsctrue / falseThis 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.

AttributeExampleDescription
payFacDataN/AData block for payment facilitator information
payFacData.payFacId12345678901The identifier provided to you, as a payment facilitator, when registered with the schemes. Note that this value will likely be different per scheme, but the fields length will always be 11 digits.

For Visa issued IDs: This ID should be 11 digits long, and padded with zeroes at the end, if your assigned ID is less than 11 characters, i.e. 12345678000.

For Mastercard issued IDs: This ID should be 11 digits long, and padded with leading zeroes if your assigned ID is less than 11 characters, i.e. 00012345678.
payFacData.subMerchantId123456789012345Identifier for the sub-merchant as registered with the schemes (15 digits, padded with leading zeroes if the ID assigned to you is less than 15 characters, i.e. 000123456789012)
payFacData.subMerchantMcc0589The MCC (or Merchant Category Code) that reflects the nature of your sub-merchant's business.
dynamicDescriptorN/ADynamic descriptor block
dynamicDescriptor.merchantNamePay*MyMerchantThis field takes the format:

PayFacName*SubMerchantName

The PayFacName cannot contain spaces. For Instance "Net In" is not a valid PayFacName.

For Payment Facilitators, if the dynamicDescriptor.merchantName doesn’t contain a * or empty space in the 4, 8 or 13 character position the create order request will be rejected with a failure message.
dynamicDescriptor.merchantAddressN/ARegistered merchant address datablock
...merchantAddress.cityDubaiRegistered merchant city
...merchantAddress.stateDubaiRegistered merchant state
...merchantAddress.countryAERegistered 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":"12345678901",
    "subMerchantId": "123456789012345",
    "subMerchantMcc": "0589"
  
  },
  "dynamicDescriptor": {
  
    "merchantName":"Pay*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:

KeyValue
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.