Credit Card Authorization
Authorizes transaction immediately but is not flagged for settlement. Authorized transactions must be capture to settle.
POST https://<PayEngine-host>/api/payment/auth
Request Body
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
transaction_amount.If set to zero or omitted, no pre-settlement fee will be deducted.
Example:
Transaction Amount: $100.00
pre_settlement_fee_charge: $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.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
transaction_amount.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)
post_settlement_fee_charge: $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.internal_transaction_id
string
An internal ID from integrating system. Will be returned in the response and associated refunds if provided.
data.order_number
string
Order number specified in billing statement of the cardholder. Alphanumeric (a-z A-Z 0-9) maximum 20 characters.
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.gratuity
string
Gratuity amount added to the original sale
data.service_charge
string
Service charges, if any
data.items
array
List of items sold
data.items[].name
string
Name of the item
data.items[].description
string
Item description
data.items[].quantity
string
Item quantity, default is 1
data.items[].is_service
string
Flag to indicate item sold is a service; default is false
data.items[].tax_rate
string
Tax rate applied to sale
data.items[].tax_amount
string
Total tax amount
data.items[].total_amount
string
Total order amount for this item/s
data.sales_tax
string
Tax amount in the transaction_amount
data.other_tax[]
array
Contains additional tax details to the transaction
data.other_tax[].name
string
Name of the tax
data.other_tax[].amount
string
Value of the tax
data.fraud_monitor_session_id
String
Fraud monitor session ID. Obtain by using PayEngine's fraud prevention javascript library.
data.surcharge_amount
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.metadata
object
Add any additional metadata by passing a json object
data.additional_data
object
Optional data. Currently, it is specific to certain use case for accounting integration
data.ip_address
string
IP address of cardholder
data.gateway_id
string
Gateway ID (optional, if multigateway mode enabled)
id
string
PayEngine payment ID for the sale request
Required
transaction_id
String
Unique transaction ID
Required
merchant_id
string
Merchant ID
Required
description
string
Transaction description
Optional
token
string
Card token provided in the request that is used to process this authorization
Required
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
order_number
string
Order number provided in the request
Optional
customer_name
string
Customer name provided in the request
Optional
auth_response.status
string
Transaction execution status. Allowed values PASS | FAIL | PENDING_3DSAUTH
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
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.items[].name
string
Item name
Optional
auth_response.items[].quantity
string
Item quantity
Optional
auth_response.items[].unit_cost
string
Item cost
Optional
auth_response.items[].description
string
Item description
Optional
auth_response.items[].total_amount
string
Total amount for the item
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
string
A boolean indicating if the transaction was partially authorized. If true, the processed amount is less than the requested amount
Required
metadata
string
Return all the metadata sent in the request
Optional
Sample Request / Response
Example Request
{
"merchant_id": "a447b0b8-0dbb-4e07-bfc2-c35bba8d71e8",
"data": {
"transaction_amount": "110.00",
"card_token": "card_sandbox_xxxx",
"order_number": "Order124",
"description": "Payment for the services",
"customer_name": "John Doe",
"ip_address": "10.10.10.10",
"sales_tax": "10",
"internal_transaction_id": "987654321",
"currency_code": "USD"
}
}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]"
}
}
}Webhook Payload Example
{
"event_uid": "9fff410f1903817978471c90e677b814",
"event": "PAYMENT_AUTH",
"data": {
"token": "card_sandbox_8Aq30HAc8TLFUFvTjqwo556i",
"sales_tax": "10",
"account_id": "fa3ac0a8-0cda-4e38-ba9d-357b0f0bd844",
"gateway_id": "1f3e0f67-d560-494c-bb1a-97558a462cc5",
"payment_id": "cd9f4405-a5c9-40a1-999d-7587f34e7b42",
"description": "Payment for the services",
"merchant_id": "1e4e6029-2cc9-4b2c-87c1-7a4b2af6d6c6",
"currency_code": "USD",
"order_number": "Order124",
"auth_response": {
"status": "PASS",
"task_id": "93461014",
"auth_code": "248293",
"card_type": "visa",
"total_amount": "110.00",
"response_code": "A0000",
"transaction_id": "47649279",
"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 05:57 PM \\n CREDIT - SALE \\n Entry Mode : KEYED \\n Transaction ID: 47649279 \\n Invoice Number: Order124 \\nDescription: Payment for the service\\n s \\n SUBTOTAL: USD $100.00 \\n SALES TAX: USD $10.00 \\n TOTAL: USD $110.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 05:57 PM \\n CREDIT - SALE \\n Entry Mode : KEYED \\n Transaction ID: 47649279 \\n Invoice Number: Order124 \\nDescription: Payment for the service\\n s \\n SUBTOTAL: USD $100.00 \\n SALES TAX: USD $10.00 \\n TOTAL: USD $110.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": "110.00",
"response_message": "Success",
"host_response_code": "00",
"masked_card_number": "1111",
"transaction_amount": "110.00",
"host_reference_number": "673084425015",
"transaction_timestamp": "2025-04-02T17:57:20",
"address_verification_code": "X",
"card_holder_verification_code": "N"
},
"customer_name": "John Doe",
"transaction_id": "5f805b55-a7e0-4ce0-83d7-a6503b04be4b",
"internal_transaction_id": "987654321"
}
}Last updated