Transaction API

The Transaction API allows users to perform various types of transaction requests through the OnePay 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.onepay.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

EMV Object

Check Object

Customer Object

Shipping Information Object

Level 2 Object

Level 3 Object

Custom Field Object

Additional Data 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.
test string	0 - Live 1 - Test	0 is default and goes through the payment processor 1 is used for onepay gateway sandbox transaction
reference_transaction_id string	up to 18 characters	The Reference Transaction ID is used to initiate post-authorization transactions such as Void, Refund, and Prior Authorization Capture.
client_ip string	up to 45 characters	The IP address of the endpoint application can be tagged along with the transaction.
device_code string	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_id string	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.
notes string	255 characters	Transaction Notes refer to additional information that can be included with a transaction.
action_code string	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_number string	Up to 100 characters	Invoice number is a unique identifier for billing and accounting purposes.
invoice_description string	up to 255 characters	An arbitrary string for describing the invoice.
purchase_order_number string	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_amount numeric	Up to 18 characters	Surcharge amount is an additional fee charged on top of a base price.

### Card Object:

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.
code numeric	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_data string	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.
ksn alphanumeric	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.
token alphanumeric	upto 1000 Characters	A token is a unique identifier generated by the gateway to represent a customer's account information securely.
pin_block alphanumeric	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_card numeric	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_code string	Up to 50 characters	Preauthorized authorization/approval code/Voucher number for Capture only transactions
voucher_number string	Minimum 6 characters	It is sent in the request when EBT card is used.
entry_mode string	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_ksn string	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_token string	Up to 32 characters	Its a temporary token generated by payment token plugin.
action_code int	1- default	The account will setup as default card for the customer profile.

EMV Object:

KEY	VALUE	DESCRIPTION
emv_data string	Up to 6000 characters	EMV Data is parsed TLV data block which received by the integrated device from the SDK.
pos_entry_mode numeric	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_type string	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_name string	Up to 255 characters	Name of the bank associated with the customer’s bank account.
check_number string	Up to 10 characters	Check number used while making transactions. To be provided only while using Back Office Conversions or Account Receivable Checks.
sec_code string	CCD, PPD, WEB, TEL, BOC, ARC	These are Sectional entry class codes which Onepay supports. ACH (SEC) Code
action_code numeric	1- default	The account will setup as default check for that customer profile.
payment_token string	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.
token alphanumeric	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_name string	Up to 50 Characters	First name associated with customer’s billing address.
last_name string	Up to 50 Characters	Last name associated with customer’s billing address.
street_1 string	Up to 50 Characters	The street address of the customer.
street_2 string	Up to 50 Characters	The street address of the customer.
city string	Up to 50 Characters	First name associated with customer’s billing address.
last_name string	Up to 50 Characters	Last name associated with customer’s billing address.
street_1 string	Up to 50 Characters	The street address of the customer.
street_2 string	Up to 50 Characters	The street address of the customer.
city string	Up to 50 Characters	If customer has city address information, it is saved on to Onepay's system
state string	Up to 50 Characters	If customer has state address information, it is saved on to Onepay's system
zip string	5 digits or 9 digits	The postal or zip code of the cardholder.
country string	Up to 50 Characters	If customer has country address information, it is saved on to Onepay's system
phone_number numeric	10 digits	If customer has phone number contact information, it is saved on to Onepay's system
company string	Up to 50 characters	If customer has company contact information, it is saved on to Onepay's system
customer_id alphanumeric	“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.
email alphanumeric	Up to 50 characters	Email address linked to customer.
email_receipt string	1- Yes 0- No	Indicator to send email receipt to customer.
notes string	Up to 250 characters	This field indicates the notes added before performing the transaction.
action_code numeric	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_decline numeric	1- Yes (default) 0- No	This flag “0-No” will not save customer on declined transactions

Shipping Information Object:

KEY	VALUE	DESCRIPTION
first_name string	Up to 50 Characters	First name associated with customer’s shipping address.
last_name string	Up to 50 Characters	Last name associated with customer’s shipping address.
company string	Up to 50 Characters	The company of the customer.
address string	Up to 50 Characters	The shipping address of the customer.
city string	Up to 50 Characters	The city details in the shipping address of the customer.
state string	Up to 50 Characters	The State details in the shipping address of the customer.
zip string	5 digits or 9 digits	The postal or zip code of the cardholder.

Custom Field Object:

KEY	VALUE	DESCRIPTION
id string	Up to 2 Characters 1 to 20	Based on the selection on Custom User defined fields and id
value string	Up to 255 Characters	Based on the selection on Custom User defined fields and values

Response Field Description:

KEY	VALUE	DESCRIPTION
transaction_response
result code string	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 code string	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 text string	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 id string	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 uid string	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_datetime string	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_type string	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_4 string	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.
amount string	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_amount string	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.
method string	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_code string	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_code string	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_result string	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.
type string	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_date string	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.
token string	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
emv string	Up to 6000 characters	Based on emv used after EMV processing. we may get Authorization Response Cryptogram (ARPC) transaction processing data
emv_tag_data string	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 mode string	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
nonce string	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.
test numeric	1- Test 0- Live (Default)	OnePay 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_name string	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_name string	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_1 string	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_2 string	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.
city string	Up to 50 Characters	If customer has city address information, it is saved on to Onepay’s system
state string	Up to 50 Characters	If customer has state address information, it is saved on to Onepay’s system
zip string	5 digits or 9 digits	The postal or zip code of the cardholder
country string	Up to 50 Characters	If customer has country address information, it is saved on to Onepay’s system
phone_number numeric	10 digits	If customer has phone number contact information, it is saved on to Onepay’s system
company string	Up to 50 characters	If customer has company contact information, it is saved on to Onepay’s system
customer_id alphanumeric	Up to 6 characters	The customer ID is either system generated or user specific
email alphanumeric	Up to 10 characters	The customer related transactions’ invoice number
email receipt numeric	Format- [email protected]	Customer email address for any email receipt
invoice_number string	1- yes 0- no	Indicator to send email receipt to customer based on any action
notes string	Transaction Notes	Customer specific notes can be provided here for additional information regarding the transactions
action_code numeric	1 digit with value 1,2 or 3.	Customer action code is an echo of transaction request
card_info
card_class alphanumeric	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_id alphanumeric	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_indicator alphanumeric	P – Prepaid Card Default: Space filled	The Prepaid Indicator feature acts to determine if the submitted card is a prepaid card.
detailcard_indicator alphanumeric	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_indicator alphanumeric	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)