The Transaction API allows users to perform various types of transaction requests through the Nilon gateway. Depending on the values entered in the fields, different types of transactions can be executed, such as sales or refunds, and various payment methods can be utilized, including credit or debit cards.
Transaction Endpoint: https://api.nilon.com/transaction
Mandatory fields are marked with an asterisk (*) to indicate that they must be provided for the request to be processed.
Request Field Description:
Request Objects:
Card Object
| ATTRIBUTE | VALUE | DESCRIPTION |
|---|---|---|
amount*numeric | Format 0 or 0.00 | The transaction amount is the total value of a transaction, including taxes and additional fees. |
method*string | CC- Credit Card ACH- Electronic Checks EBT: Electronic Benefit Transfer DB: Debit Card | The method refers to the mode of payment used to complete a transaction. |
type*numeric | 1, 2, 3, 4, 5, 7, 9, 11, 13 | The Transaction Type field is mandatory and is used to specify the type of transaction being processed. Details of each transaction type can be found here. |
nonce*string | up to 50 characters | A mandatory unique variable assigned to every new transaction. However, it is not required for prior authorization, void, or refund transactions. |
teststring | 0 - Live 1 - Test | 0 is default and goes through the payment processor 1 is used for Nilon gateway sandbox transaction |
reference_transaction_idstring | up to 18 characters | The Reference Transaction ID is used to initiate post-authorization transactions such as Void, Refund, and Prior Authorization Capture. |
client_ipstring | up to 45 characters | The IP address of the endpoint application can be tagged along with the transaction. |
device_codestring | 2 - IDTECH 38 - MAGTEK 40 - PAX 41 - MIURA | This code identifies the device with which the card present transaction is made. |
market_code*string | R : Retail E :Ecommerce M :MOTO | Market code is used to indicate on how the transaction is made, whether it is Card present or Online or Mail/Telephone order. |
pos_idstring | up to 20 characters | The field that identifies the specific device or point of entry where the transaction originated is known as the Point of Sale (POS) ID. |
notesstring | 255 characters | Transaction Notes refer to additional information that can be included with a transaction. |
action_codestring | 1 - Retrieve transaction 2 - Signature update 3 - Transaction receipt request 4 - Reprocess transaction | The Action Code in a payment processing request refers to a code that indicates the type of action that is being requested for a particular transaction. |
invoice_numberstring | Up to 100 characters | Invoice number is a unique identifier for billing and accounting purposes. |
invoice_descriptionstring | up to 255 characters | An arbitrary string for describing the invoice. |
purchase_order_numberstring | Up to 20 characters | An optional reference number that can be used to link a transaction with a corresponding purchase order from the customer. |
surcharge_amountnumeric | Up to 18 characters | Surcharge amount is an additional fee charged on top of a base price. |
| KEY | VALUE | DESCRIPTION |
|---|---|---|
number*string | Up to 50 characters | Card number is a mandatory field for card-based transactions. It is required to provide the cardholder's credit card number in order to process the transaction successfully. |
codenumeric | 3 to 4 Digits | Card security code also known as the Card Verification Value (CVV) which is a three-digit code for Visa, Mastercard, and Discover cards, and a four-digit code for American Express cards. |
expiration_date*numeric | MMYY | The card expiration date is a mandatory field for card transactions. It refers to the month and year when the credit or debit card will expire. |
track_datastring | Up to 6000 | Track data is the information encoded within the magnetic strip on the back of a credit card which is read by the electronic reader within the terminal. |
ksnalphanumeric | Upto 20 Characters | The Key Serial Number (KSN) is a unique identifier associated with an encryption key used for securing sensitive data, such as track data. In encrypted card transactions, the KSN may be required if it is not already included in the encryption block. |
tokenalphanumeric | upto 1000 Characters | A token is a unique identifier generated by the gateway to represent a customer's account information securely. |
pin_blockalphanumeric | Up to 20 characters | The PIN (Personal Identification Number) is a numeric code used for authentication in certain types of card-based transactions. If a PIN block is present, it is required to be provided in the transaction. These measures ensure the secure processing of PIN-based transactions and protect the confidentiality of sensitive information. |
default_cardnumeric | 1 - default | The account that is being set up will be designated as the default account for the customer profile. This means that it will be the primary or default payment method associated with the customer, and transactions will be processed using this account by default unless specified otherwise. |
auth_codestring | Up to 50 characters | Preauthorized authorization/approval code/Voucher number for Capture only transactions |
voucher_numberstring | Minimum 6 characters | It is sent in the request when EBT card is used. |
entry_modestring | 00 - Unknown 01 -Manual 02 -Magnetic stripe 05 -Integrated circuit card (ICC). 07 - Contactless Integrated Circuit Read 80 - EMV fallback to Magnetic Strip entry | Point-of-Service (POS) Entry Mode(Tag-9F39,Source-Terminal,Format-n 2,Length-1,P/C-primitive)Indicates the method by which the PAN was entered, according to the first two digits of the ISO 8583:1987 POS Entry Mode A two-character POS Entry Mode field indicates the method by which the PAN was entered, according to the first two digits of the ISO 8583:1987 POS Entry Mode. |
pin_ksnstring | Upto 20 characters | An identifier known as the “Key Serial Number” (KSN) is returned from the encrypting device, along with the cryptogram. The KSN is formed from the device's unique identifier, and an internal transaction counter. |
payment_tokenstring | Up to 32 characters | Its a temporary token generated by payment token plugin. |
action_codeint | 1- default | The account will setup as default card for the customer profile. |
EMV Object:
| KEY | VALUE | DESCRIPTION |
|---|---|---|
emv_datastring | Up to 6000 characters | EMV Data is parsed TLV data block which received by the integrated device from the SDK. |
pos_entry_modenumeric | 00Unspecified 01 Manual (Key entered) 05 Integrated Circuit Read (CVV data Reliable) 07 Contactless Integrated Circuit Read (Reliable) 10 Credential on File 79 EMV fallback to manual entry 80 EMV fallback to Magnetic Strip entry 86 EMV Transaction switched from Contactless to Contact entry 90 Magnetic Stripe - Track Read 91 Contactless Magnetic Stripe Read 95 Integrated Circuit Read (CVV data unreliable) | The POS entry mode indicates the type of card entry. This is specific to EMV transactions. |
Check:
| KEY | VALUE | DESCRIPTION |
|---|---|---|
aba_code*alphanumeric | 9 digits | The routing number is a nine-digit code that is specific to a particular bank or financial institution. It is used to identify the financial institution during the processing of electronic transactions, such as direct deposits, wire transfers, and automated clearinghouse (ACH) transactions. |
account_typestring | Checking- 0, Saving- 1, Business- 2 | Nature or type of bank accounts refers to the classification or categorization of accounts based on their purpose or characteristics. |
bank_namestring | Up to 255 characters | Name of the bank associated with the customer’s bank account. |
check_numberstring | Up to 10 characters | Check number used while making transactions. To be provided only while using Back Office Conversions or Account Receivable Checks. |
sec_codestring | CCD, PPD, WEB, TEL, BOC, ARC | These are Sectional entry class codes which Nilon supports. ACH (SEC) Code |
action_codenumeric | 1- default | The account will setup as default check for that customer profile. |
payment_tokenstring | Up to 32 characters | The term "payment_token" typically refers to a secure token that represents sensitive payment information, such as credit card details or a digital wallet token. It is often used in the context of online or mobile payments to enhance security and protect the user's financial data. |
tokenalphanumeric | Up to 1000 characters | Unique alphanumeric value generated by the gateway. This can be used for token based transactions. |
Customer Object:
| KEY | VALUE | DESCRIPTION |
|---|---|---|
first_namestring | Up to 50 Characters | First name associated with customer’s billing address. |
last_namestring | Up to 50 Characters | Last name associated with customer’s billing address. |
street_1string | Up to 50 Characters | The street address of the customer. |
street_2string | Up to 50 Characters | The street address of the customer. |
citystring | Up to 50 Characters | First name associated with customer’s billing address. |
last_namestring | Up to 50 Characters | Last name associated with customer’s billing address. |
street_1string | Up to 50 Characters | The street address of the customer. |
street_2string | Up to 50 Characters | The street address of the customer. |
citystring | Up to 50 Characters | If customer has city address information, it is saved on to Nilon's system |
statestring | Up to 50 Characters | If customer has state address information, it is saved on to Nilon's system |
zipstring | 5 digits or 9 digits | The postal or zip code of the cardholder. |
countrystring | Up to 50 Characters | If customer has country address information, it is saved on to Nilon's system |
phone_numbernumeric | 10 digits | If customer has phone number contact information, it is saved on to Nilon's system |
companystring | Up to 50 characters | If customer has company contact information, it is saved on to Nilon's system |
customer_idalphanumeric | “AUTO” for auto generated id’s starts from 100000 OR User Generated e.g. CID001 | The customer ID is either system generated or user specific. |
emailalphanumeric | Up to 50 characters | Email address linked to customer. |
email_receiptstring | 1- Yes 0- No | Indicator to send email receipt to customer. |
notesstring | Up to 250 characters | This field indicates the notes added before performing the transaction. |
action_codenumeric | 1- Add customer - If record exists, update customer (default in virtual terminal) 2- Add customer - if exists, do not update 3- Add customer - if exists ,throw error 4 - Delete customer | Based on the action code, customer related updates can be performed. If nothing sent or invalid value no update or add will occur |
save_on_declinenumeric | 1- Yes (default) 0- No | This flag “0-No” will not save customer on declined transactions |
Shipping Information Object:
| KEY | VALUE | DESCRIPTION |
|---|---|---|
first_namestring | Up to 50 Characters | First name associated with customer’s shipping address. |
last_namestring | Up to 50 Characters | Last name associated with customer’s shipping address. |
companystring | Up to 50 Characters | The company of the customer. |
addressstring | Up to 50 Characters | The shipping address of the customer. |
citystring | Up to 50 Characters | The city details in the shipping address of the customer. |
statestring | Up to 50 Characters | The State details in the shipping address of the customer. |
zipstring | 5 digits or 9 digits | The postal or zip code of the cardholder. |
Custom Field Object:
| KEY | VALUE | DESCRIPTION |
|---|---|---|
idstring | Up to 2 Characters 1 to 20 | Based on the selection on Custom User defined fields and id |
valuestring | Up to 255 Characters | Based on the selection on Custom User defined fields and values |
Response Field Description:
| KEY | VALUE | DESCRIPTION |
|---|---|---|
| transaction_response | ||
result codestring | 1 - Approved 2 - Declined 3 - Error | The overall status of the transaction refers to the current state or condition of the transaction, indicating whether it is successful, pending, failed, or any other relevant status. |
result sub codestring | 000- Approval | The response sub code is a code that provides additional information or context about the response status of a transaction. It further specifies the reason or outcome of the transaction, helping to provide more detailed information about its status. |
result textstring | Up to 100 characters APPROVAL DECLINED | The description of the outcome of the transaction from the processor refers to the detailed explanation or message provided by the payment processor regarding the result of the transaction. It may include information about the success or failure of the transaction, any error messages, or specific details related to the processing of the payment. |
transaction idstring | Up to 6 digits | The gateway assigned transaction ID is a unique identifier assigned by the payment gateway to each transaction request. It serves as a reference to track and identify the specific transaction within the gateway's system. |
transaction uidstring | Up to 50 characters | The GUID value associated with the transaction is a globally unique identifier that uniquely identifies the transaction within a system or across systems. It is often used as a reference or identifier for tracking and retrieving transaction-related information. |
transaction_datetimestring | Format- yyyyMMddTHHmmss | The Date and Time in UTC of the transaction response refers to the specific date and time when the response for the transaction was generated by the system, using Coordinated Universal Time (UTC) as the standard time reference. It helps in accurately tracking and recording the timing of the transaction processing. |
account_typestring | MASTER CARD- MC VISA- VI AMEX- AX DISCOVER- DS JCB- JC DINERS- DC | The card brand refers to the specific payment network or brand associated with the account used for the transaction. It indicates the type of card being used, such as Visa, MasterCard, American Express, Discover, or other card networks. |
account_last_4string | Last 4 card digits | The last four digits of the card used for the transaction are the final four digits of the card number, typically displayed for reference and verification purposes. |
amountstring | Format 0 or 0.00 | The transaction amount requested in the original authorization refers to the specific amount that was initially authorized for the transaction when it was first processed. This amount may be different from the actual settled amount, as adjustments or modifications can occur during the transaction process. |
approved_amountstring | Format 0 or 0.00 | The amount approved refers to the specific amount that has been authorized by the payment processor for the transaction. It indicates the maximum amount that can be charged or captured for the transaction based on the approval received from the processor. |
methodstring | CC- Credit card ACH- Automated Clearing House EBT- Electronic Benefit Transfer DB- Debit Card | The method used to perform the transaction refers to the specific payment method or instrument used for the transaction, such as credit card, debit card, or alternative payment methods like PayPal or digital wallets. |
auth_codestring | OK | When a sale transaction is processed, a unique code, often referred to as a transaction ID or authorization code, is generated by the payment processor to identify and reference the specific transaction. This code serves as a confirmation that the transaction was successfully authorized and can be used for further processing or reference purposes. |
avs_result_codestring | AVS Result Code | The result of checking the cardholder’s postal code and any additional address information provided against the Issuer’s system of record |
code_resultstring | CVV Result Code | CVV result code refers to the response code indicating the verification result of the Card Verification Value (CVV) provided during a transaction. CVV is a three- or four-digit security code found on the back of credit and debit cards. |
typestring | 1- AuthOnly 2- AuthCapture 3- Prior Auth Capture 4- Capture Only 5- Void 7- Credit 9- Verification 11- Balance Inquiry 13-Retrieve Transaction | The type of transaction performed is returned in this field. It indicates the nature of the transaction, such as sale, authorization, capture, refund, void, or other transaction types. The specific transaction type will be specified in the response, allowing you to determine the type of action that was performed for the given transaction. |
expiration_datestring | MMYY | The card's expiration date refers to the month and year in which the card will expire. It is an important piece of information associated with a payment card, as it indicates the date after which the card should no longer be used for transactions. |
tokenstring | alphanumeric value generated by token generation process | In the context of payment gateways, a card token is a unique identifier or token generated by the payment gateway to represent a specific credit card or payment method. It serves as a substitute for the actual card details, providing an additional layer of security by reducing the exposure of sensitive card information. |
| EMV_data | ||
emvstring | Up to 6000 characters | Based on emv used after EMV processing. we may get Authorization Response Cryptogram (ARPC) transaction processing data |
emv_tag_datastring | Up to 6000 characters | EMV tag data consists of various data elements, each identified by a unique tag. These tags represent specific information related to the cardholder, the card issuer, and the transaction. Some common examples of EMV tags include: |
entry modestring | emv- pos_entrymode | Data processed through device 05 – Integrated Circuit Read 07 – Contactless Integrated Circuit Read 80 – EMV fallback to Magnetic Strip entry 91 – Contactless Magnetic Stripe Read |
noncestring | Any valid value(Timestamp) | A unique transaction number is assigned to every new transaction as a reference for transactions received by the gateway. However, it is not required for prior authorization, void, or refund transactions. |
testnumeric | 1- Test 0- Live (Default) | Nilon gateway offers different modes for transaction processing, allowing merchants to configure how their transactions are handled. The mode for transaction processing determines how transactions are processed and the resulting actions taken by the gateway. |
| customer | ||
first_namestring | Up to 50 Characters | The first name associated with a customer's billing address refers to the given name or personal name of the customer as it appears in their billing information. It is typically the customer's first or given name that is used for billing and identification purposes |
last_namestring | Up to 50 Characters | The last name associated with a customer's billing address refers to the surname or family name of the customer as it appears in their billing information. It is typically the customer's last name that is used for billing and identification purposes |
street_1string | Up to 50 Characters | The street 1 address of the customer refers to the primary address line associated with their billing address. It typically includes the house/building number, street name, and any additional address details necessary for locating the customer's residence or place of business. |
street_2string | Up to 50 Characters | The street 2 address of the customer refers to an additional line of address information associated with their billing address. It is used to provide further details or instructions that may help in locating the customer's residence or place of business. |
citystring | Up to 50 Characters | If customer has city address information, it is saved on to Nilon’s system |
statestring | Up to 50 Characters | If customer has state address information, it is saved on to Nilon’s system |
zipstring | 5 digits or 9 digits | The postal or zip code of the cardholder |
countrystring | Up to 50 Characters | If customer has country address information, it is saved on to Nilon’s system |
phone_numbernumeric | 10 digits | If customer has phone number contact information, it is saved on to Nilon's system |
companystring | Up to 50 characters | If customer has company contact information, it is saved on to Nilon's system |
customer_idalphanumeric | Up to 6 characters | The customer ID is either system generated or user specific |
emailalphanumeric | Up to 10 characters | The customer related transactions’ invoice number |
email receiptnumeric | Format- [email protected] | Customer email address for any email receipt |
invoice_numberstring | 1- yes 0- no | Indicator to send email receipt to customer based on any action |
notesstring | Transaction Notes | Customer specific notes can be provided here for additional information regarding the transactions |
action_codenumeric | 1 digit with value 1,2 or 3. | Customer action code is an echo of transaction request |
| card_info | ||
card_classalphanumeric | B-Business C-Consumer P-Purchase T-Corporate | Categorizes the BIN as a Business card, Corporate T&E card, Purchase card or Consumer card. Assists the POS device with prompting decisions – to collect addenda or not. Visa, MasterCard and Discover only |
product_idalphanumeric | Up to 3 characters | These values indicate card product sub categories (Purchase Card, Business Card, etc.) for Visa, MasterCard, and Discover. Values are subject to change at any time |
prepaid_indicatoralphanumeric | P – Prepaid Card Default: Space filled | The Prepaid Indicator feature acts to determine if the submitted card is a prepaid card. |
detailcard_indicatoralphanumeric | C-(Credit) Credit Hybrid (meaning it has PIN capability also). E-(Debit) Debit – PIN Only with EBT. H-(Debit) (Debit) Debit Hybrid (PIN and Signature). J-(Debit) USA Commercial Debit – Signature Only – Not PIN Capable. K-(Debit) USA Commercial Debit – PIN Capable. L-(Debit) NON USA Consumer Debit – Not PIN Capable. M-(Debit) NON USA Commercial Debit – Not PIN Capable. N-(Debit) NON USA Consumer Debit – PIN Capable O-(Debit) NON USA Commercial Debit – PIN Capable P-(Debit) Debit – PIN Only without EBT. R-(Credit) Private Label (MasterCard) S-(Debit) Signature only (not PIN capable). X-(Credit) True credit (– Not PIN Capable/ NoSignature capability) | Determines the card type (credit, debit, prepaid) usage (pin, signature etc.) and PIN/Signature capability. |
debitnetwork_indicatoralphanumeric | Sample – 05D07E25P30P00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 | Debit Network/PINless Indicator is a 3 byte value. First 2 bytes indicates the debit network followed by the 1 byte PINless Indicator. There can be up to 20 Debit Net`w works/PINless Indicators Example: 03E56P 00 00 00 03 (Pulse) E (PINless POS) 56 (STAR EAST FISERV) P (Pinned POS) |