Credit Card Authorization V2

Authorizes transaction immediately but is not flagged for settlement. Authorized transactions must be capture to settle.

In the V2 Auth we add support for 3DS and some improvements.

POST https://<PayEngine-host>/api/v2/payment/auth

Request

Request Body

Name
Type
Description

merchantId*

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

string

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

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

data.internalTransactionId

string

An internal ID from integrating system. Will be returned in the response and associated refunds if provided.

data.currencyCode

string

ISO Currency Code if not provided it defaults to US Dollar (USD)

data.salesTax

string

Tax amount in the transactionAmount

data.orderNumber

string

Order number specified in billing statement of the cardholder. Alphanumeric (a-z A-Z 0-9) maximum 20 characters.

data.order_id

string

Identifier assigned by the merchant

data.customerName

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

string

List of items sold

data.items[].name

string

Name of the item

data.items[].quantity

string

Item quantity, default is 1

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[].commodity.code

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[].unitOfCost

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.

attempt3DSecure

boolean

Indicate whether this transaction should attempt 3D Secure or not. It's false by default.

browserInfo

string

Required if attempt3DSecure is set to true

data.description

String

Transaction Description. Character limit is 255

data.additonalData

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

String

IP address of cardholder

data.gateway_id

string

Gateway ID (optional, if multigateway mode enabled)

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

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

string

True / False. True if 3DS is attempted

Optional

ThreeDSType

string

Type of 3DS attempted. Allowed values frictionless | challenge | attempted

Optional

ThreeDSStatus

string

3DS attempt status. Allowed values succeeded | failed

Optional

gratuity

string

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

Optional

AuthResponse.status

string

Transaction execution status. Allowed values PASS | FAIL | PENDING_3DSAUTH

Required

AuthResponse.responseCode

string

The code representing the status of the processed request

Required

AuthResponse.responseMessage

string

The corresponding message for the response code

Required

AuthResponse.authCode

string

Authorization code received for the transaction

Optional

AuthResponse.hostReferenceNumber

string

A unique reference number by the acquiring processor for each transaction

Optional

AuthResponse.hostResponseCode

string

Response code indicating the status of the authorization request

Optional

AuthResponse.taskID

string

Task identification number from acquiring processor

Required

AuthResponse.transactionID

string

Transaction Identifier

Optional

AuthResponse.transactionTimestamp

string

Transaction timestamp in merchant's timezone

Required

AuthResponse.transactionAmount

string

Total amount requested in this transaction

Optional

AuthResponse.processedAmount

string

Total amount processed in this transaction

Optional

AuthResponse.totalAmount

string

Total amount of this transaction

Optional

AuthResponse.addressVerificationCode

string

Address verification system response

Optional

AuthResponse.cardHolderVerificationCode

string

CVV verification code

Optional

AuthResponse.cardType

string

Card Type - visa, mastercard, american express, discover, dinersclub, ebt

Required

AuthResponse.maskedCardNumber

string

The truncated card number displaying the last four digits

Required

AuthResponse.customerReceipt

string

Printable customer receipt

Required

AuthResponse.merchantReceipt

string

Printable merchant receipt

Required

Metadata

string

Return all the metadata sent in the request

Optional

device

object

Device Object. This would exist for device based transactions

Optional

device.id

string

Device ID

device.type

string

Device Type

device.name

string

Device Name

device.model

string

Device Model

device.serial_number

string

Device Serial Number

device.manufacturer

string

Device Manufacturer

device.app_version

string

Device App Version

device.os

string

Device Operating System

device.os_version

string

Device OS version

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)

{
    "merchantId": "1e4e6029-2cc9-4b2c-87c1-7a4b2af6d6c6",
    "data": {
        "transactionAmount": "1.00",
        "cardToken": "card_sandbox_8Aq30HAc8TLFUFvTjqwo556i",
        "description": "Description of transaction",
        "currencyCode": "USD",
        "salesTax": "1.00",
        "gratuity":"10.00",
        "orderNumber": "12345678910",
        "internalTransactionID": "987654321",
        "customerName": "John Wick",
        "ip_address": "123.111.21.2",
        "metadata": {
            "customerId": "123",
            "email" : "[email protected]"
        }
    }
}

Example Request (via clear PAN) NOTE Requires PCI Certifcation

{
    "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 3DS

{
    "merchantId": "a447b0b8-0dbb-4e07-bfc2-c35bba8d71e8",
    "attempt3DSecure": true,
    "browserInfo": "COLLECTED USING CLIENT BROWSER",    
    "data": {
        "transactionAmount": "110.00",
        "cardToken": "card_sandbox_xxxx",
        "description": "Payment for the service"
    }
}

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

PreviousIntroductionNextVoid Credit Authorization

Last updated