Sale/Purchase
An API for Sale/Purchase transactions in a card payment system enables a client application—such as a card terminal —to initiate and process a standard payment transaction where a customer pays for goods or services. Here's what it typically does:
Key Parameters:
MsgType.SALE: Indicates a sale.tokenReq: Iftrue, requires tokenization (agreement fields are used).agreementID/agreementType: Required for tokenized transactions.
What a Sale/Purchase Transaction API Does
1
Initiates a Payment Request
It sends a structured request to Payment Orchestration, including:
- Transaction amount
- Currency
- Merchant ID
- Card details or token
- Transaction type (e.g. SALE, PURCHASE)
2
Handles Card Data Securely
It transmits card information (e.g. PAN, expiry, CVV) or tokenised data using secure protocols (e.g. TLS, PCI-DSS compliant encryption).
3
Triggers Authentication
Depending on the card type and configuration, it may prompt for:
- PIN entry
- Signature
4
Processes Authorisation
The API communicates with Payment Orchestration to:
- Validate the card
- Check available funds
- Authorise the transaction
5
Returns a Response
It provides a response to the client app, including:
- Approval or decline status
- Authorisation code
- Transaction ID
- Error codes (if any)
6
Supports Receipt Generation
The response can be used to generate a customer receipt with transaction details.
7
Logs and Reconciliation
The transaction is logged for reporting, settlement, and reconciliation purposes.
Disclaimers / Consent
The app/merchant should allow for the display of disclaimers/collect consent whenever applicable. eg. during Tokenization.
If requesting a token for a cardholder, you need to ensure the merchant collects consent from the customer to allow the merchant to store the card token information and to perform future transactions
1
2
3
4
5
6
7
8
9
10
11
12
13
14
Button.onClick {
val parsedAmount = parseAmount(amount) ?: return@onClick
val requestMsg = RequestMsg(
msgType = MsgType.SALE,
invoiceNbr = "10120304",
amount = 1500, // $15.00
currency = "USD",
readerType = ReaderType.INSERT_CLESS_SWIPE,
tokenReq = true,
agreementID = "MERCH123_20250804_001",
agreementType = "I"
)
sdk.sendRequestMessage(requestMsg)
}