Credit Card Sale
The credit card sale API obtains real-time authorization for a Credit Card Sale transaction and enters the transaction into the Unsettled batch
POST https://<PayEngine-host>/api/payment/sale
Request
Request Body
merchant_id*
string
Merchant ID
transactionMonitoringBypass
boolean
Optional flag to explicitly skip transaction monitoring rules.
data.transactionAmount*
string
Max Length=12 Allowed characters: 0-9 and .(dot) Note: this value always reflects the total dollar amount for example 1.00 and 1 both will be considered $1.00 and 0.10 will be 10 cents.
data.gratuity
string
The final gratuity amount, included in the transaction, associated with the purchase.
data.preSettlementFeeCharge
string
An optional fee amount to be deducted from the transaction before settlement. This fee is processed at the processor level and reduces the net amount settled to the merchant. The value must be a positive number and cannot exceed the total transaction amount. Applicable in scenarios where the merchant needs to collect fees separately or adjust the settlement amount.
Constraints:
Must be a positive decimal number.
Cannot be greater than the
transactionAmount.If set to zero or omitted, no pre-settlement fee will be deducted.
Example:
Transaction Amount: $100.00
preSettlementFeeCharge: $5.00Net Settlement to Merchant: $95.00 (after deducting the $5.00 fee)
Note: The customer will still be charged the full transaction amount of $100.00, but the merchant will receive $95.00 due to the $5.00 pre-settlement fee deduction.
data.postSettlementFeeCharge
string
An optional fee amount to be deducted after the transaction has been settled at the processor level but before the net amount is paid out to the merchant. This fee adjusts the final payout to the merchant while maintaining the full transaction amount charged to the customer. Note:
Use this parameter for fees such as processing charges, administrative fees, or adjustments that need to be applied after settlement but before the payout to the merchant.
Applicable for scenarios where deductions are required post-transaction processing.
Constraints:
Must be a positive decimal number.
Cannot exceed the total
transactionAmount.If omitted or set to zero, no post-settlement fee will be deducted.
Example:
Transaction Amount: $100.00
Settlement Amount: $100.00 (full amount settled)
postSettlementFeeCharge: $7.50Net Payout to Merchant: $92.50 (after deducting the $7.50 fee)
Note: The customer will still see a charge of $100.00 for the transaction. The deduction is applied only to the merchant's payout after the settlement.
data.cardToken*
string
Card token generated by PayEngine secure field API Not supported in SoftPOS SDK
data.store_payment_method
boolean
true | false – Indicates whether the card should be stored for future use. Set to true to store the card. Defaults to true
data.initiated_by
string
merchant | customer – Indicates who initiated the transaction. Defaults to customer
attempt3DSecure
boolean
Indicates whether this transaction should attempt 3D Secure or not. By default sale API doesn't attempt 3DS Note: As per Visa 3DS mandate, cardholder's email or phone number is mandatory. If attempt3DSecure is true and card type is visa and liability shift required by partner = yes and email/phone is not present then the transaction will fail due to cardholder email/phone not being present Not supported in SoftPOS SDK
browserInfo
string
Required if attempt3DSecure is set to true
Not Supported in SoftPOS SDK
data.order_number
string
Order number or PO number specified in billing statement of the cardholder. Alphanumeric (a-z A-Z 0-9) maximum 20 characters Note: This field is required for Level II and Level III data
data.internalTransactionID
String
An internal ID from integrating system. Will be returned in the response and associated refunds if provided.
data.customer_name
string
If a name other than the card holder's name is required to be shown on the transaction list, it is important to note that this alternative name will not serve as the card holder's name during card authorization.
data.taxCode
string
Tax code which is declared in accounting software
data.addressLine1
string
Address Line 1
Commonly the house number and street name on the cardholder’s / customer’s account or billing address. Address Verification Service (AVS) data compared with the address on the card issuer’s file.
data.zip
string
Postal or ZIP Code
ZIP code on the cardholder’s account or billing address. (AVS) data compared with the postal or ZIP code on the card issuer’s file.
data.order_id
string
Identifier assigned by the merchant
data.items
string
List of items sold Note: This field is required for Level III data
data.items[].name
string
Name of the item Note: This field is required for Level III data
data.items[].quantity
string
Item quantity, default is 1
Note: This field is required for Level III data
data.items[].productCode
string
Description code of the item Note: This field is required for Level III data
data.items[].description
string
Item descriptions Note: This field is required for Level III data
data.items[].commodityCode
string
International description code of the individual good or service being supplied. Note: This field is required for Level III data
data.items[].unitOfMeasure
string
Unit of measurement Default: Each Note: This field is required for Level III data
data.items[].unitCost
string
Unit cost of item
Note: This field is required for Level III data
data.items[].taxAmount
string
Amount on sales tax on specific item Default: 0.00 Note: This field is required for Level III data
data.items[].taxRate
string
Percentage representing the value-added tax applied Default: 0.00 Note: This field is required for Level III data
data.items[].totalAmount*
string
Total order amount for this item/s Note: This field is required for Level III data
data.sales_tax
string
Tax amount in the transactionAmount.
Note: This field is required for Level II and Level III data
data.other_tax[]
array
Contains additional tax details applied to the transaction
data.other_tax[].name
string
Name of the tax (e.g., Bottle Deposit Fee) Note: It is required if data.other_tax[].amount is provided
data.other_tax[].amount
string
Value of the tax and it is included in the transaction Note: It is required if data.other_tax[].name is provided
data.fraudMonitorSessionId
string
Fraud monitor session ID. Obtain by using PayEngine's fraud prevention javascript library.
data.surchargeAmount
string
Max Length=12 Allowed characters: 0-9 and .(dot)
The surcharge amount should be included in the transaction amount.
Note: this value always reflects the total dollar amount for example 1.00 and 1 both will be considered $1.00 and 0.10 will be 10 cents.
data.description
string
Transaction Description. Character limit is 255
data.additional_data
object
Optional data. Currently, it is specific to certain use case for accounting integration
data.metadata
object
Add any additional metadata by passing a json object
data.gateway_id
string
Gateway ID (optional, if multigateway mode enabled)
data.ip_address
string
IP address of cardholder
data.shippingAmount
string
Shipping amount to be included in the transaction amount. Default is 0.00 Note: This field is required for Level III data
data.shippingCountry
string
Shipping Country e.g. US Default will be Merchant's country Note: This field is required for Level III data
data.shipFromPostal
string
Postal/ZIP code of the address from where purchased goods are being shipped, defaults to merchant profile postal code. Note: This field is required for Level III data
data.shippingPostal
string
Postal/ZIP code of the address where purchased goods will be delivered. This field can be identical to the 'shipFromPostal' if the customer is present and takes immediate possession of the goods. Note: This field is required for Level III data
data.commodityCode
string
4 character international description code of the overall goods or services being supplied Note: This field is required for Level III data
data.kount.user_defined_fields
object
This is optional. Add the user defined values in Kount Portal and pass the same field name (should be exactly same) and value in this object. For example, if a user defined value called "fieldName1" is added in Kount portal, then the field name should be fieldName1 in this object.
Note: All the blue colored parameters are required for Level III data
ID
string
PayEngine system ID for the sale request
Required
TransactionID
String
Unique transaction ID
Required
MerchantID
string
Merchant ID
Required
gateway_id
string
ID of the gateway through which the transaction is processed.
Optional
Description
string
Transaction Description
Optional
token
string
The card token used to process this transaction, as provided in the request. This field will be included in the response only if store_payment_method is set to true.
Required
store_payment_method
boolean
Indicates whether the card is stored for future use.
Optional
initiated_by
string
Indicates who initiated the transaction.
Optional
internalTransactionID
string
Internal Transaction ID provided in the request
Optional
order_number
string
Order number provided in the request
Optional
customer_name
string
Customer name provided in the request
Optional
currencyCode
string
ISO Currency code provided in the request Note: Only returned if originally provided in the request
Required
ThreeDSActionRequired
boolean
Indicates whether 3DS challenge needs to be initiated
Required
ThreeDSType
string
Type of 3DS attempted. Allowed values frictionless | challenge | attempted
Optional
ThreeDSStatus
string
3DS status. Allowed values succeeded | failed
Optional
gratuity
string
The final gratuity amount, included in the transaction, associated with the purchase.
Optional
SaleResponse.status
string
Transaction execution status. Allowed values PASS | FAIL | PENDING_3DSAUTH
Required
SaleResponse.responseCode
string
The code representing the status of the processed request. It comes from the processor
Required
SaleResponse.responseMessage
string
The corresponding message for the response code and it comes from the processor
Required
SaleResponse.authCode
string
Authorization code received for the transaction
Optional
SaleResponse.hostReferenceNumber
string
A unique reference number by the acquiring processor for each transaction. If it fails, before sending to processor, then the values be a. D (represents 3DS failed) b. 2 (represents failure)
Optional
SaleResponse.hostResponseCode
string
Optional
SaleResponse.taskID
string
Task identification number from acquiring processor
Required
SaleResponse.transactionID
string
Transaction Identifier
Optional
SaleResponse.transactionTimestamp
string
Transaction timestamp in merchant's timezone
Required
SaleResponse.transactionAmount
string
Total amount requested in this transaction
Optional
SaleResponse.processedAmount
string
Total amount processed in this transaction
Optional
SaleResponse.totalAmount
string
Total amount of this transaction
Optional
SaleResponse.cardType
string
Card Type - visa, mastercard, american express, discover, dinersclub, ebt
Required
SaleResponse.maskedCardNumber
string
The truncated card number displaying the last four digits
Required
SaleResponse.aci
string
When VISA is used, the returned Authorization Characteristics Indicator (ACI). This one character value provides information concerning the transaction's CPS qualification status.
Optional
SaleResponse.ucafCollectionIndicator
string
When Mastercard is used, Universal Cardholder Authentication Field.
Optional
saleResponse.fraudScore
int
Return the fraud score between 0 - 100. 100 means less confidence i.e. more fraudulent i and 0 means lower chance of fraudulent. Note: The fraud monitoring has to be enabled. Please contact support to enable it
Optional
saleResponse.kountScore
int
Return the Kount Omniscore
Optional
SaleResponse.customerReceipt
string
Printable customer receipt
Required
SaleResponse.merchantReceipt
string
Printable merchant receipt
Required
SaleResponse.partialPayment
string
A boolean indicating if the transaction was partially processed. If true, the processed amount is less than the requested amount
Required
Metadata
object
Return all the metadata sent in the request
Optional
ID
string
PayEngine system ID for the sale request
Required
TransactionID
string
Unique transaction ID
Required
MerchantID
string
Merchant ID
Required
ThreeDSActionRequired
boolean
Indicates whether 3DS challenge needs to be initiated
Required
SaleResponse.status
string
Transaction execution status. If ThreeDSActionRequired is returned as true this status us set to PENDING_3DSAUTH
Required
Sample Request / Response
Sample Response for Error case
Sample Response when the card token is expired
Sample Response when card is not found
Sample Response when 3DS is failed is not found
Sample Response when Kount fails the transaction
Last updated