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

data.transactionAmount*

string

Max Length=12 Allowed characters: 0-9 and .(dot)

This amount should be inclusive of gratuity amount if present

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.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.cardToken*

string

Card token generated by PayEngine secure field API

attempt3DSecure

boolean

Indicates whether this transaction should attempt 3D Secure or not. By default sale API doesn't attempt 3DS

browserInfo

string

Required if attempt3DSecure is set to true

data.currencyCode

string

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

data.gratuity

string

The final gratuity amount, included in the transaction, associated with the purchase.

data.sales_tax

string

Tax amount in the transactionAmount. Note: This field is required for Level II and Level III data

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

string

Identifier assigned by the merchant

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

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

description

string

Transaction Description

Optional

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

Response code indicating the status of the authorization request

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

Address verification system response

Optional

SaleResponse.cardHolderVerificationCode

string

CVV verification codes

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

Commercial card type

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

Mastercard purchase transaction type

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

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 wil apply.

Sample Request / Response

Example Request (via Token)

{
    "merchant_id": "a447b0b8-0dbb-4e07-bfc2-c35bba8d71e8",
    "data": {
        "transactionAmount": "110.00",
        "cardToken": "card_sandbox_xxxx",
        "order_number": "Order124",
        "description": "Payment for the services",
        "customer_name": "John Doe",
        "ip_address": "10.10.10.10",
        "sales_tax": "10",
        "gratuity": "10.00",
        "internalTransactionID": "987654321",
        "currencyCode": "USD"
    }
}

Example Request (via clear PAN) NOTE: Requires PCI Certification

{
    "merchantId": "a447b0b8-0dbb-4e07-bfc2-c35bba8d71e8",
    "data": {
        "transactionAmount": "110.00",
        "card_number":"4242424242424242",
        "card_exp": "09/28",
        "card_cvc": "982",
        "card_holder_name": "John Doe",
        "token_type": "none|pe|network"
        "description":"Payment for the service"
    }
}

Example request with metadata

{
    "merchant_id": "a447b0b8-0dbb-4e07-bfc2-c35bba8d71e8",
    "data": {
        "transactionAmount": "110.00",
        "cardToken": "card_sandbox_xxxx",
        "description": "Payment for the services",
        "metadata": {             
            "customerId": "123",
            "email": "[email protected]"
        }
    }
}

Example Request with 3DS

{
    "merchant_id": "a447b0b8-0dbb-4e07-bfc2-c35bba8d71e8",
    "attempt3DSecure": true,
    "browserInfo": "COLLECTED USING CLIENT BROWSER",    
    "data": {
        "transactionAmount": "110.00",
        "cardToken": "card_sandbox_xxxx",
        "Description": "Payment for the services",
        "metadata": {
            "customerId": "123",
            "email" : "[email protected]"
        }
    }
}

Example Request with Additional Data

{
    "merchant_id": "a447b0b8-0dbb-4e07-bfc2-c35bba8d71e8",
    "data": {
        "transactionAmount": "110.00",
        "cardToken": "card_sandbox_xxxx",
        "Description": "Payment for the services",
        "additionalData": {
            "loanNumber": "L255525"
        },
        "metadata": {
            "customerId": "123",
            "email" : "[email protected]"
        }
    }
}

Example Request with Optional Kount Data

{
    "merchant_id": "a447b0b8-0dbb-4e07-bfc2-c35bba8d71e8",
    "data": {
        "transactionAmount": "110.00",
        "cardToken": "card_sandbox_xxxx",
        "Description": "Payment for the services",
        "additionalData": {
            "loanNumber": "L255525"
        },
        "kount": {
              "user_defined_fields": {
              "fieldName1": "Value1",
              "fieldName2": "Value2"
          },
        }
    }
}

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

PreviousCredit Card CaptureNextACH Sale

Last updated