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. |
| paymentAttempts | 3 | You can give the customer an option to retry the payment attempt incase of failure. Max value 5. |
| 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 | AE | 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 | 12345678901 | The 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.subMerchantId | 123456789012345 | Identifier 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.subMerchantMcc | 0589 | The MCC (or Merchant Category Code) that reflects the nature of your sub-merchant's business. |
| dynamicDescriptor | N/A | Dynamic descriptor block |
| dynamicDescriptor.merchantName | Pay*MyMerchant | This field takes the format:PayFacName*SubMerchantNameThe 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.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":"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:
| 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.