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://<Platform-host>/api/payment/sale

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. Not supported in SoftPOS SDK (Amount is provided as part of the startTransaction API parameter)

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

string

Card token generated by Platform secure field API Not supported in SoftPOS SDK

attempt_3d_secure

boolean

Indicates whether this transaction should attempt 3D Secure or not. By default sale API doesn't attempt 3DS Note: As per Visa 3DS mandate, cardholder's email or phone number is mandatory. If attempt_3d_secure 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 Not supported in SoftPOS SDK

browser_info

string

Required if attempt_3d_secure is set to true Not Supported in SoftPOS SDK

data.currency_code

string

ISO Currency code If not provided it defaults to US Dollar (USD) Not supported in SoftPOS SDK (Currency code is provided as part of the startTransaction API parameter)

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

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 cardholder's name needs to be shown on the transaction list, include it in this field. Note that this alternative name will not be used as the cardholder's name during card authorization.

data.tax_code

string

Tax code which is declared in accounting software

data.address_line_1

string

Address Line 1

Commonly the house number and street name on the cardholder's / customer's account or billing address. Address Verification Service (AVS) data compared with the address on the card issuer's file.

data.zip

string

Postal or ZIP Code

ZIP code on the cardholder's account or billing address. (AVS) data compared with the postal or ZIP code on the card issuer's file.

data.items

array

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

string

Unit of measurement Default: Each Note: This field is required for Level III data

data.items[].unit_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 and this amount is included in the item amount Default: 0.00 Note: This field is required for Level III data

data.items[].total_amount

string

Total order amount for this item/s including the individual item tax Note: This field is required for Level III data

data.sales_tax

string

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

data.other_tax[]

array

Contains additional tax details applied to the transaction

data.other_tax[].name

string

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

data.other_tax[].amount

string

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

data.fraud_monitor_session_id

string

Fraud monitor session ID. Obtain by using Platform's fraud prevention javascript library. Check this reference for how to generate the fraud monitor session ID Not supported in SoftPOS SDK

data.surcharge_amount

string

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

The surcharge amount 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.additional_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.gateway_id

string

Gateway ID (optional, if multigateway mode enabled)

data.ip_address

string

IP address of cardholder

data.shipping_amount

string

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

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 'ship_from_postal' 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

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. Not supported in SoftPOS SDK

Note: All the blue colored parameters are required for Level III data

Response

Field Name
Type
Description
Required?

id

string

Platform payment ID for the sale request

Required

transaction_id

string

Unique transaction ID

Required

merchant_id

string

Merchant ID

Required

gateway_id

string

ID of the gateway through which the transaction is processed.

Optional

description

string

Transaction Description

Optional

token

string

Platform token associated with the transaction

Required

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

currency_code

string

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

Optional

three_ds_action_required

boolean

Indicates whether 3DS challenge needs to be initiated

Required

three_ds_type

string

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

Optional

three_ds_status

string

3DS status. Allowed values succeeded | failed

Optional

sale_response.status

string

Transaction execution status. Allowed values PASS | FAIL | PENDING_3DSAUTH

Required

sale_response.response_code

string

The code representing the status of the processed request. It comes from the processor

Required

sale_response.response_message

string

The corresponding message for the response code and it comes from the processor

Required

sale_response.auth_code

string

Authorization code received for the transaction

Optional

sale_response.host_reference_number

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

sale_response.host_response_code

string

Response code indicating the status of the authorization request

Optional

sale_response.task_id

string

Task identification number from acquiring processor

Required

sale_response.transaction_id

string

Transaction Identifier

Optional

sale_response.transaction_timestamp

string

Transaction timestamp in merchant's timezone

Required

sale_response.transaction_amount

string

Total amount requested in this transaction. For example, if the transactionAmount in the request is $100, then this SaleResponse.transactionAmount is also $100

Optional

sale_response.processed_amount

string

The actual amount processed by the processor. In standard processing, processedAmount is same as transactionAmount . The differences become relevant when features like partial authorization or multi-currency are enabled. For example, 1. With partial authorization, transactionAmount represents the requested amount, processedAmount the actual processed amount, and a partial indicator is set to 'yes'. Without partial authorization, insufficient funds will result in transaction failure. 2. With multi-currency enabled, the transactionAmount is $100 CAD, and the processedAmount will be $80 USD (if the merchant's currency is in USD)

Optional

sale_response.total_amount

string

The total amount for this transaction. In standard processing, totalAmount is same as transactionAmount as well as processedAmount . If a separate fee is applied, totalAmount will exceed transactionAmount.

Optional

sale_response.sales_tax

string

Tax amount in the transactionAmount.

Optional

sale_response.address_verification_code

string

Address verification system response

Optional

sale_response.card_holder_verification_code

string

CVV verification codes

Optional

sale_response.card_type

string

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

Required

sale_response.masked_card_number

string

The truncated card number displaying the last four digits

Required

sale_response.commercial_card

string

Commercial card type

Optional

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

sale_response.transaction_integrity_classification

string

Mastercard purchase transaction type

Optional

sale_response.ucaf_collection_indicator

string

When Mastercard is used, Universal Cardholder Authentication Field.

Optional

sale_response.fraud_score

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

sale_response.kount_score

int

Return the Kount Omniscore

Optional

sale_response.customer_receipt

string

Printable customer receipt

Required

sale_response.merchant_receipt

string

Printable merchant receipt

Required

sale_response.partial_payment

string

A boolean indicating if the transaction was partially processed. 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": "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 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 services"
    }
}

Example Request with Metadata

{
    "merchant_id": "a447b0b8-0dbb-4e07-bfc2-c35bba8d71e8",
    "data": {
        "transaction_amount": "110.00",
        "card_token": "card_sandbox_xxxx",
        "description": "Payment for the services",
        "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": [
          {
              "id" : "Item123",
              "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"
             }
         ]
    }
}

Example Request with Additional Data

{
    "merchant_id": "a447b0b8-0dbb-4e07-bfc2-c35bba8d71e8",
    "data": {
        "transaction_amount": "110.00",
        "card_token": "card_sandbox_xxxx",
        "description": "Payment for the services",
        "additional_data": { 
            "loan_number": "L255525"
        }
    }
}

Example Request with Optional Kount Data

{
    "merchant_id": "a447b0b8-0dbb-4e07-bfc2-c35bba8d71e8",
    "data": {
        "transaction_amount": "110.00",
        "card_token": "card_sandbox_xxxx",
        "description": "Payment for the services",
        "kount": {
            "user_defined_fields": {
                "field_name1": "Value1",
                "field_name2": "Value2"
            }
        }
    }
}

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

Webhook event: PAYMENT_SALE

Webhook Payload Example

{
    "event_uid": "d2e9f63779ad668603a51b563ec68b6f",
    "event": "PAYMENT_SALE",
    "data": {
        "token": "card_sandbox_8Aq30HAc8TLFUFvTjqwo556i",
        "metadata": {
            "email": "[email protected]",
            "customer_id": "123"
        },
        "sales_tax": "10",
        "account_id": "fa3ac0a8-0cda-4e38-ba9d-357b0f0bd844",
        "gateway_id": "1f3e0f67-d560-494c-bb1a-97558a462cc5",
        "payment_id": "62430b78-3049-4d25-9637-b78f3ea16709",
        "description": "Payment for the services",
        "merchant_id": "1e4e6029-2cc9-4b2c-87c1-7a4b2af6d6c6",
        "currency_code": "USD",
        "order_number": "Order124",
        "customer_name": "John Doe",
        "sale_response": {
            "status": "PASS",
            "task_id": "90687488",
            "auth_code": "165201",
            "card_type": "visa",
            "total_amount": "110.00",
            "response_code": "A0000",
            "transaction_id": "69832290",
            "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:49 PM         \\n           CREDIT - SALE            \\n         Entry Mode : KEYED         \\n      Transaction ID: 69832290      \\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:49 PM         \\n           CREDIT - SALE            \\n         Entry Mode : KEYED         \\n      Transaction ID: 69832290      \\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": "990551169365",
            "transaction_timestamp": "2025-04-02T17:49:08",
            "address_verification_code": "X",
            "card_holder_verification_code": "N"
        },
        "transaction_id": "8760a4f8-51fd-46eb-a3b4-32f08e05e487",
        "internal_transaction_id": "987654321"
    }
}
PreviousCredit Card CaptureNextBatch Sale

Last updated