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. Not all are required, and not all will be returned to your in all cases.
| Attribute | Example | Comments |
|---|---|---|
| action | "AUTH", "SALE" | 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 | TBC | TBC |
| payFacData.saleOrgId | TBC | TBC |
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.