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

Name
Type
Description

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.00

  • Net 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.50

  • Net 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.currencyCode

string

ISO Currency code If not provided it defaults to US Dollar (USD)

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

Field Name
Type
Description
Required?

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

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.addressVerificationCode

string

Optional

SaleResponse.cardHolderVerificationCode

string

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.commercialCard

string

Optional

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.transactionIntegrityClassification

string

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

When automatic Network Tokenization is activated on your account, the transactions will be completed using card brand tokens and respective benefits will apply.

Sample Request / Response

Example Request (via Token)

Example Request with 3DS

Example request with metadata

Example Request with items

Example Request with Additional Data

Example Request with Optional Kount Data

For complete 3DS flow please refer to our 3D Secure developer guide.

Last updated