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://<Platform-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) 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.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.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
data.cardToken*	string	Card token generated by Platform 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.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.salesTax	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.fraudMonitorSessionId	String	Fraud monitor session ID. Obtain by using Platform'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.metadata	object	Add any additional metadata by passing a json object
data.additionalData	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)
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

200

Field Definitions

Field Name	Type	Description	Required?
ID	string	Platform 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
orderNumber	string	Order number value provided in the request	Optional
token	string	The card token used to process this authorization, as provided in the request. This field will be included in the response only if store_payment_method is set to true.	Optional
store_payment_method	boolean	Indicates whether the card is stored for future use.	Optional
initiated_by	string	Indicates who initiated the transaction. Must be provided in the request.	Optional
currencyCode	string	ISO Currency code provided in the request Note: Only returned if originally provided in the request	Optional
internalTransactionID	string	Internal Transaction ID provided in the request	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
AuthResponse.partialPayment	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

Request

Example Request (via token)

{
    "merchantId": "1e4e6029-2cc9-4b2c-87c1-7a4b2af6d6c6",
    "data": {
        "transactionAmount": "30.00",
        "cardToken": "card_sandbox_8Aq30HAc8TLFUFvTjqwo556i",
        "store_payment_method": true,
        "initiated_by": "customer",
        "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 with Items

{
    "merchantId": "a447b0b8-0dbb-4e07-bfc2-c35bba8d71e8",
    "attempt3DSecure": true,
    "browserInfo": "COLLECTED USING CLIENT BROWSER",    
    "data": {
        "transactionAmount": "200.20",
        "cardToken": "card_sandbox_xxxx",
        "Description": "Payment for the services",
        "items": [
          {
              "name": "Sample",
              "unitCost": "95.00",
              "quantity": 2,
              "totalAmount": "190.00" //included in the transaction amount
            }
         ],
         "sales_tax": "10.00",
         "other_tax": [
             {
                 "name": "CRV",
                 "amount": "0.20"
             }
         ],
        "metadata": {
            "customerId": "123",
            "email" : "[email protected]"
        }
    }
}

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",
        "orderNumber": "12345678910",
        "metadata": {
            "customerId": "123",
            "email" : "[email protected]"
        }
    }
}

Response

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