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 Body

Name
Type
Description

merchant_id*

string

Merchant ID

transaction_monitoring_bypass

boolean

Optional flag to explicitly skip transaction monitoring rules.

data.transaction_amount*

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

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

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

string

Shipping amount to be included in the transaction amount. Default is 0.00 Note: This field is required for Level III data

data.card_token*

string

Card token generated by PayEngine secure field API

data.internal_transaction_id

string

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

data.currency_code

string

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

data.order_number

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

array

List of items sold

data.items[].name

string

Name of the item

data.items[].quantity

string

Item quantity, default is 1

data.items[].product_code

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

string

Unit of measurement Default: Each

Note: This field is required for Level III data

data.items[].unit_of_cost

string

Unit cost of item

Note: This field is required for Level III data

data.items[].tax_rate

string

Percentage representing the value-added tax applied Default: 0.00

Note: This field is required for Level III data

data.items[].tax_amount

string

Amount on sales tax on specific item. It is included in the transactionAmount.Default: 0.00

Note: This field is required for Level III data

data.items[].total_amount

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

data.other_tax[]

array

Contains additional tax details applied to the transaction.

data.other_tax[].name

string

Name of the tax (e.g. CRV). Note: It is required if data.other_tax[].amount is provided

data.other_tax[].amount

string

Value of the tax applied and it is included in the transaction amount Note: It is required if data.other_tax[].name is provided

data.fraud_monitor_session_id

String

Fraud monitor session ID. Obtain by using PayEngine's fraud prevention javascript library.

attempt_3d_secure

boolean

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

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

browser_info

string

Required if attempt3DSecure is set to true

data.description

String

Transaction Description. Character limit is 255

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

String

IP address of cardholder

data.gateway_id

string

Gateway ID (optional, if multigateway mode enabled)

data.shipping_country

string

Shipping Country e.g. US Default will be Merchant's country

Note: This field is required for Level III data

data.ship_from_postal

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

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

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 payment ID for the auth request

Required

transaction_id

String

Unique transaction ID for this request

Required

merchant_id

string

Merchant ID provided in the request

Required

gateway_id

string

ID of the gateway through which the transaction is processed

Optional

description

string

Transaction Description

Optional

order_number

string

Order number value provided in the request

Optional

customer_name

string

Customer name provided in the request

Optional

token

string

Card token provided in the request that is used to process this authorization

Optional

currency_code

string

ISO Currency code provided in the request Note: Only returned if originally provided in the request

Optional

internal_transaction_id

string

Internal Transaction ID provided in the request

Optional

three_ds_action_required

string

True / False. True if 3DS is attempted

Optional

three_ds_type

string

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

Optional

three_ds_status

string

3DS attempt status. Allowed values succeeded | failed

Optional

auth_response.status

string

Transaction execution status. Allowed values PASS | FAIL | PENDING_3DSAUTH

Required

auth_response.response_code

string

The code representing the status of the processed request

Required

auth_response.response_message

string

The corresponding message for the response code

Required

auth_response.auth_code

string

Authorization code received for the transaction

Optional

auth_response.host_reference_number

string

A unique reference number by the acquiring processor for each transaction

Optional

auth_response.host_response_code

string

Response code indicating the status of the authorization request

Optional

auth_response.task_id

string

Task identification number from acquiring processor

Required

auth_response.transaction_id

string

Transaction Identifier

Optional

auth_response.transaction_timestamp

string

Transaction timestamp in merchant's timezone

Required

auth_response.transaction_amount

string

Total amount requested in this transaction

Optional

auth_response.processed_amount

string

Total amount processed in this transaction

Optional

auth_response.total_amount

string

Total amount of this transaction

Optional

auth_response.sales_tax

string

Sales tax

Optional

auth_response.address_verification_code

string

Address verification system response

Optional

auth_response.card_holder_verification_code

string

CVV verification code

Optional

auth_response.card_type

string

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

Required

auth_response.masked_card_number

string

The truncated card number displaying the last four digits

Required

auth_response.customer_receipt

string

Printable customer receipt

Required

auth_response.merchant_receipt

string

Printable merchant receipt

Required

auth_response.partial_payment

boolean

A boolean indicating if the transaction was partially authorized. 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 wil apply.

Sample Request / Response

Example Request (via token)

{
    "merchant_id": "1e4e6029-2cc9-4b2c-87c1-7a4b2af6d6c6",
    "data": {
        "transaction_amount": "1.00",
        "card_token": "card_sandbox_8Aq30HAc8TLFUFvTjqwo556i",
        "description": "Description of transaction",
        "currency_code": "USD",
        "sales_tax": "1.00",
        "order_number": "12345678910",
        "internal_transaction_id": "987654321",
        "customer_name": "John Wick",
        "ip_address": "123.111.21.2",
        "metadata": {
            "customer_id": "123",
            "email" : "[email protected]"
        }
    }
}

Example Request with Items

{
    "merchant_id": "a447b0b8-0dbb-4e07-bfc2-c35bba8d71e8",
    "attempt_3d_secure": true,
    "browser_info": "COLLECTED USING CLIENT BROWSER",    
    "data": {
        "transaction_amount": "200.20",
        "card_token": "card_sandbox_xxxx",
        "description": "Payment for the services",
        "items": [
          {
              "name": "Sample",
              "unit_cost": "95.00",
              "quantity": 2,
              "total_amount": "190.00" //included in the transaction amount
            }
         ],
         "sales_tax": "10.00",
         "other_tax": [
             {
                 "name": "CRV",
                 "amount": "0.20"
             }
         ],
        "metadata": {
            "customer_id": "123",
            "email" : "[email protected]"
        }
    }
}

Example Request with 3DS

{
    "merchant_id": "a447b0b8-0dbb-4e07-bfc2-c35bba8d71e8",
    "attempt_3d_secure": true,
    "browser_info": "COLLECTED USING CLIENT BROWSER",    
    "data": {
        "transaction_amount": "110.00",
        "card_token": "card_sandbox_xxxx",
        "description": "Payment for the service",
        "order_number": "123"
        "metadata": {
            "customer_id": "123",
            "email" : "[email protected]"
        }
    }
}

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

Webhook event: PAYMENT_AUTH

Webhook Payload Example

{
    "event_uid": "6d8f4292ec5bbc49d5b088948925a3cd",
    "event": "PAYMENT_AUTH",
    "data": {
        "token": "card_sandbox_8Aq30HAc8TLFUFvTjqwo556i",
        "metadata": {
            "email": "[email protected]",
            "customer_id": "123"
        },
        "sales_tax": "1.00",
        "account_id": "fa3ac0a8-0cda-4e38-ba9d-357b0f0bd844",
        "gateway_id": "1f3e0f67-d560-494c-bb1a-97558a462cc5",
        "ip_address": "123.111.21.2",
        "payment_id": "c968e08b-9307-4fd7-9692-771b3d79d916",
        "description": "Description of transaction",
        "merchant_id": "1e4e6029-2cc9-4b2c-87c1-7a4b2af6d6c6",
        "order_number": "12345678910",
        "currency_code": "USD",
        "customer_name": "John Wick",
        "auth_response": {
            "status": "PASS",
            "task_id": "61126431",
            "auth_code": "993357",
            "card_type": "visa",
            "total_amount": "1.00",
            "response_code": "A0000",
            "transaction_id": "13008528",
            "partial_payment": false,
            "customer_receipt": "        Sandbox US Merchant         \\n        200 Epcot Center Dr         \\n         Orlando, FL 32836          \\n            800-490-8514            \\n                 \\n                 \\n        2025-04-02 06:09 PM         \\n           CREDIT - SALE            \\n         Entry Mode : KEYED         \\n      Transaction ID: 13008528      \\n    Invoice Number: 12345678910     \\nDescription: Description of transact\\n                ion                 \\n        SUBTOTAL: USD $0.00         \\n        SALES TAX: USD $1.00        \\n          TOTAL: USD $1.00          \\n                 \\n                 \\n       NO SIGNATURE REQUIRED        \\n              APPROVED              \\n                 \\n                 \\n                 \\n                 \\n                 \\n                 \\n                 \\n                 \\n                 \\n                 \\n           Customer Copy            \\n",
            "merchant_receipt": "        Sandbox US Merchant         \\n        200 Epcot Center Dr         \\n         Orlando, FL 32836          \\n            800-490-8514            \\n                 \\n                 \\n        2025-04-02 06:09 PM         \\n           CREDIT - SALE            \\n         Entry Mode : KEYED         \\n      Transaction ID: 13008528      \\n    Invoice Number: 12345678910     \\nDescription: Description of transact\\n                ion                 \\n        SUBTOTAL: USD $0.00         \\n        SALES TAX: USD $1.00        \\n          TOTAL: USD $1.00          \\n                 \\n                 \\n      X_______________________      \\nI AGREE TO PAY ABOVE TOTAL AMOUNT IN\\n ACCORDANCE WITH CARD ISSUER's AGREE\\nMENT (MERCHANT AGREEMENT IF CREDIT V\\n              OUCHER)               \\n     KEEP COPY FOR YOUR RECORDS     \\n               \\n \\n                \\n              APPROVED              \\n                 \\n                 \\n                 \\n                 \\n                 \\n                 \\n                 \\n                 \\n                 \\n                 \\n           Merchant Copy            \\n",
            "processed_amount": "1.00",
            "response_message": "Success",
            "host_response_code": "00",
            "masked_card_number": "1111",
            "transaction_amount": "1.00",
            "host_reference_number": "691121564407",
            "transaction_timestamp": "2025-04-02T18:09:05",
            "address_verification_code": "X",
            "card_holder_verification_code": "N"
        },
        "transaction_id": "689c6d9c-999f-4904-8129-a024dc413782",
        "internal_transaction_id": "987654321"
    }
}
PreviousCredit Card AuthorizationNextVoid Credit Authorization

Last updated