# Cardholder Present source: https://developer.mastercard.com/mastercard-gateway/documentation/gateway-features/trans-enrich-data/cardholder-present-data/index.md ## Overview {#overview} Cardholder Present (CHP) payments refer to transactions using a Point of Sale (POS) terminal. The terminal may read card data by: * dipping an EMV card * NFC (Near Field Communication) from a contactless card * swiping a magnetic stripe card * keying the card number Tip: Integrate with API version 100 for full compatibility. Support for CHP is available from Gateway API version 40 and later. A CHP payment is initiated by a terminal and sent to the gateway as a Verify, Authorize, Capture, Pay, or Refund transaction. For example, transactions that are authorized offline by the chip on the card will be sent as a Capture only, whereas transactions requiring authorization by the issuer will use an online Authorize transaction, and then a Capture transaction. CHP transactions interwork with many of the other gateway features. You can: * tokenize the card * refund using the same integration as your e-commerce transactions, or through the UI * unify e-commerce and CHP reporting ## Prerequisites {#prerequisites} Your payment service provider and your acquirer must enable you for cardholder present transactions. ## Common Fields Used for CHP Transactions {#common-fields-used-for-chp-transactions} The following API fields are relevant to all cardholder present integrations through the gateway. ### Mandatory Fields {#mandatory-fields} * `transaction.source`=CARD_PRESENT: If you do not provide this field, the default transaction source configured on your acquirer link by your payment service provider will be used. [\[REST\]](https://developer.mastercard.com/mastercard-gateway/documentation/api-reference/v100/rest/api-ops/index.md#transaction) [\[NVP\]](https://developer.mastercard.com/mastercard-gateway/documentation/api-reference/v100/nvp/api-ops/index.md#transaction) * `sourceOfFunds.type`=CARD [\[REST\]](https://developer.mastercard.com/mastercard-gateway/documentation/api-reference/v100/rest/api-ops/index.md#transaction) [\[NVP\]](https://developer.mastercard.com/mastercard-gateway/documentation/api-reference/v100/nvp/api-ops/index.md#transaction) * `order.amount` [\[REST\]](https://developer.mastercard.com/mastercard-gateway/documentation/api-reference/v100/rest/api-ops/index.md#transaction) [\[NVP\]](https://developer.mastercard.com/mastercard-gateway/documentation/api-reference/v100/nvp/api-ops/index.md#transaction) * `order.currency` [\[REST\]](https://developer.mastercard.com/mastercard-gateway/documentation/api-reference/v100/rest/api-ops/index.md#transaction) [\[NVP\]](https://developer.mastercard.com/mastercard-gateway/documentation/api-reference/v100/nvp/api-ops/index.md#transaction) * Card number: It is mandatory to provide the card number but depending on the card read manner, through key entry, magnetic stripe, or EMV chip, you may provide it in: * `sourceOfFunds.provided.card.number` for [keyed transactions](https://developer.mastercard.com/mastercard-gateway/documentation/gateway-features/trans-enrich-data/cardholder-present-data/index.md#process-a-keyed-transaction). * `sourceOfFunds.provided.card.track1` and/or `sourceOfFunds.provided.card.track2` for [magnetic stripe transactions](https://developer.mastercard.com/mastercard-gateway/documentation/gateway-features/trans-enrich-data/cardholder-present-data/index.md#process-a-magnetic-stripe-transaction), or their EMV tag equivalents, tag 56 and tag 57, respectively provided in `sourceOfFunds.provided.card.emvRequest` for contactless transactions where card data is in magnetic stripe format. * Tag 5A in `sourceOfFunds.provided.card.emvRequest` for [EMV transactions (contact or contactless)](https://developer.mastercard.com/mastercard-gateway/documentation/gateway-features/trans-enrich-data/cardholder-present-data/index.md#process-an-emv-transaction) where card data is in EMV format. * `sourceOfFunds.provided.card.p2pe.payload` for [Point-to-Point Encryption (P2PE)](https://developer.mastercard.com/mastercard-gateway/documentation/gateway-features/trans-enrich-data/cardholder-present-data/point-to-point-encry/index.md) transactions where card data is in DUKPT encrypted format. * Terminal identifier: It is mandatory to provide the terminal identifier but depending on the card read manner, through key entry, magnetic stripe, or EMV chip, you may provide it in: * `posTerminal.lane` for [keyed transactions](https://developer.mastercard.com/mastercard-gateway/documentation/gateway-features/trans-enrich-data/cardholder-present-data/index.md#process-a-keyed-transaction) and [magnetic stripe transactions](https://developer.mastercard.com/mastercard-gateway/documentation/gateway-features/trans-enrich-data/cardholder-present-data/index.md#process-a-magnetic-stripe-transaction). * Tag 9F1C in `sourceOfFunds.provided.card.emvRequest` for [EMV transactions (contact/contactless)](https://developer.mastercard.com/mastercard-gateway/documentation/gateway-features/trans-enrich-data/cardholder-present-data/index.md#process-an-emv-transaction) where card data is in EMV format. ### Optional Fields {#optional-fields} Ensure that values for the following POS terminal fields are set correctly based on how the terminal generated the card data for the transaction. If data for these fields is available, always provide it. The gateway will pass the data as required to the acquirer. If the acquirer requires a field and if it is not present, then the transaction will fail. * `posTerminal.address` * `posTerminal.attended`: If you do not provide this field, the gateway defaults the value to UNKNOWN_OR_UNSPECIFIED * `posTerminal.authorizationMethod` * `posTerminal.cardHolderActivated`: If you do not provide this field, the gateway defaults the value to NOT_CARDHOLDER_ACTIVATED * `posTerminal.inputCapability`: This field is mandatory for EMV transactions. * `posTerminal.location`: This field is mandatory for EMV transactions. * `posTerminal.panEntryMode` * `posTerminal.pinEntryCapability` * `posTerminal.onlineReasonCode`: This field is mandatory for chip and chip fallback transactions (including reversals) for all online transactions. * `posTerminal.serialNumber` * `posTerminal.mobile.cardInputDevice`: This field applies to mobile POS (mPOS) devices where the device can accept tap on a screen or physical keypad for entering the PIN. Software PIN should only be used for devices that do not have a hardware keypad to support PIN Entry. For mPOS integration requirements, see [Integrating to use mPOS](https://developer.mastercard.com/mastercard-gateway/documentation/gateway-features/trans-enrich-data/cardholder-present-data/index.md#integrating-to-use-mpos). **POS Terminal API Reference** [\[REST\]](https://developer.mastercard.com/mastercard-gateway/documentation/api-reference/v100/rest/api-ops/index.md#transaction) [\[NVP\]](https://developer.mastercard.com/mastercard-gateway/documentation/api-reference/v100/nvp/api-ops/index.md#transaction) * `order.gratuityAmount`: Provide this field if the payment includes a gratuity amount. [\[REST\]](https://developer.mastercard.com/mastercard-gateway/documentation/api-reference/v100/rest/api-ops/index.md#transaction) [\[NVP\]](https://developer.mastercard.com/mastercard-gateway/documentation/api-reference/v100/nvp/api-ops/index.md#transaction) * `order.cashbackAmount`: Provide this field if the payment includes a cashback amount. [\[REST\]](https://developer.mastercard.com/mastercard-gateway/documentation/api-reference/v100/rest/api-ops/index.md#transaction) [\[NVP\]](https://developer.mastercard.com/mastercard-gateway/documentation/api-reference/v100/nvp/api-ops/index.md#transaction) * `order.cashAdvance`: Provide this field if the payment includes a cash advance amount. [\[REST\]](https://developer.mastercard.com/mastercard-gateway/documentation/api-reference/v100/rest/api-ops/index.md#transaction) [\[NVP\]](https://developer.mastercard.com/mastercard-gateway/documentation/api-reference/v100/nvp/api-ops/index.md#transaction) ### Point-Of-Sale (POS) support {#point-of-sale-pos-support} * **Standard POS** This is a cardholder verification method in which the PIN is authenticated online, directly with the card issuer. * **Tap on Phone** Tap on Phone enables merchants to accept payments using their NFC-enabled smartphones, eliminating the need for a traditional POS terminal. Warning: * Certain fields require different values depending on the payment scheme or type of POS being used. * Transit-related fields are only required for specific use cases within the transit domain. The following fields are required to process Authorize and Pay requests. | API field | Required input | |--------------------------------------------------------------------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `order.amount` | The total amount for the order. | | `order.currency` | ISO 4217, alpha code. For example, USD, GBP. | | `transaction.source` | CARD_PRESENT | | `transaction.transit` | For Transit use cases, fields are required. For more details, see the [Transit](https://developer.mastercard.com/mastercard-gateway/documentation/gateway-features/trans-enrich-data/cardholder-present-data/transit/index.md) section. | | `posTerminal.cardPresenceCapability` | CARD_PRESENT | | `posTerminal.attended` | ATTENDED | | `posTerminal.cardholderActivated` | Tap on Phone - Standard POS - MPOS_ACCEPTANCE_DEVICE NOT_CARDHOLDER_ACTIVATED | | `posTerminal.mobile.cardInput.Device` | Tap on Phone - BUILT_IN SEPARATE_DONGLE INTEGRATED_DONGLE | | `posTerminal.location` | MERCHANT_TERMINAL_ON_PREMISES | | `posTerminal.lane` | Use a unique Terminal ID for the device Do not use a fixed Terminal ID value across the estate | | `posTerminal.inputCapability` | CONTACTLESS_CHIP | | `posTerminal.pinEntry` capability Tap on Phone (MPoC/SPoC) for **Mastercard** - Tap on Phone (MPoC/SPoC) for **Visa** - Tap on Phone (CPoC) - Standard POS - | SOFTWARE_ONLINE_PIN_ONLY for BUILT_IN PIN_SUPPORTED FOR INTEGRATED or SEPARATE DONGLE MPOS PIN_NOT_SUPPORTED for BUILT_IN PIN_SUPPORTED for standard POS with online PIN connectivity | | `posTerminal.pinLengthCapability` | Numeric 4-12 Required for terminals with PIN Entry capability | | `pos.Terminal.singleTapIndicator` | True or False: When terminal supports single tap with PIN | | `transaction.targetTransactionID` | Required for terminals supporting single tap with PIN when submitting the second transaction following a DECLINED_WITH_PIN_REQUIRED response | | `posTerminal.panEntryMode` Tap on Phone - Standard POS - | CONTACTLESS - Tap on Phone CONTACTLESS or CHIP or SWIPE-WITH-SIGNATURE or SWIPE or KEYED | | `posTerminal.onlineReasonCode` | CHIP_APPLICATION_DATA_FILE, CHIP_COMMON_DATA_FILE_ERROR, FORCED_BY_CHIP, FORCED_BY_ISSUER, FORCED_BY_MERCHANT, FORCED_BY_TERMINAL, MERCHANT_SUSPICIOUS, OVER_FLOOR_LIMIT, RANDOM_SELECTION_BY_TERMINAL, UNABLE_TO_PROCESS_CHIP | | `sourceOfFunds.type` | CARD | | `sourceOfFunds.provided.card.emvRequest` | EMV tags as per the [Supported EMV Tags](https://developer.mastercard.com/mastercard-gateway/documentation/gateway-features/trans-enrich-data/cardholder-present-data/index.md#supported-emv-tags) table. | | `SourceOfFunds.provided.card.track2` | Track2 | | `sourceOfFunds.provided.card.expiry.month ` | Expiry Month, length 2, Digits 1-12 | | `sourceOfFunds.provided.card.expiry.year` | Expiry Year, length 2, Digits 00-99 | | `sourceOfFunds.provided.card.sequenceNumber` | Application PAN Sequence Number (APSN) | | `sourceOfFunds.provided.card.pin` | For Online Pin support | ### Examples of Standard POS with online pin {#examples-of-standard-pos-with-online-pin} ### Authorization {#authorization} | HTTP Method | URL | |-------------|------------------------------------------------------------------------------------------------------------------| | PUT | https://{{host}}/api/rest/version/latest/merchant/CYG_S2I_MER2/order/{{order_id}}/transaction/{{transaction_id}} | ```json { "apiOperation": "AUTHORIZE", "order": { "amount": "20", "currency": "USD" }, "transaction": { "source": "CARD_PRESENT" }, "sourceOfFunds": { "type": "CARD", "provided": { "card": { "number": "5133333333333338", "expiry": { "month": "12", "year": "25" }, "emvRequest": { "5F34": "03", "82": "3000", "95": "0000008000", "9F02": "000000002000", "9A": "191105", "5F2A": "840", "9F1A": "404", "9F10": "0210A5800F040400000000000000000000FF", "9F34": "410302", "9F36": "0027", "9C": "00", "9F26": "E4754D7F5695F63B", "9F27": "80", "9F37": "162D6807", "9F33": "60B8C8" }, "sequenceNumber": "003" } } }, "posTerminal": { "address": { "country": "AUS", "postcodeZip": "5000" }, "inputCapability": "CHIP", "panEntryMode": "CHIP", "pinEntryCapability": "PIN_SUPPORTED", "location": "MERCHANT_TERMINAL_ON_PREMISES", "lane": "Lane_03", "attended": "ATTENDED", "serialNumber": "56464646", "onlineReasonCode": "FORCED_BY_MERCHANT", "cardPresenceCapability": "CARD_PRESENT", "cardholderActivated": "NOT_CARDHOLDER_ACTIVATED" } } ``` ```json { "authorizationResponse": { "commercialCard": "123", "commercialCardIndicator": "1", "date": "0723", "financialNetworkCode": "MCC", "posData": "0000004000900", "posEntryMode": "051", "processingCode": "003000", "responseCode": "00", "stan": "142118", "time": "072226", "transactionIdentifier": "401655599", "transactionIntegrityClass": "A1" }, "gatewayEntryPoint": "WEB_SERVICES_API", "merchant": "CYG_S2I_MER2", "order": { "amount": 20.00, "authenticationStatus": "AUTHENTICATION_NOT_IN_EFFECT", "certainty": "FINAL", "chargeback": { "amount": 0, "currency": "USD" }, "creationTime": "2025-07-23T07:22:26.209Z", "currency": "USD", "id": "AKS_442597558", "lastUpdatedTime": "2025-07-23T07:22:26.389Z", "merchantAmount": 20.00, "merchantCategoryCode": "4111", "merchantCurrency": "USD", "status": "AUTHORIZED", "totalAuthorizedAmount": 20.00, "totalCapturedAmount": 0.00, "totalDisbursedAmount": 0.00, "totalRefundedAmount": 0.00 }, "posTerminal": { "address": { "country": "AUS", "postcodeZip": "5000" }, "attended": "ATTENDED", "cardPresenceCapability": "CARD_PRESENT", "cardholderActivated": "NOT_CARDHOLDER_ACTIVATED", "inputCapability": "CHIP", "lane": "Lane_03", "location": "MERCHANT_TERMINAL_ON_PREMISES", "onlineReasonCode": "FORCED_BY_MERCHANT", "panEntryMode": "CHIP", "pinEntryCapability": "PIN_SUPPORTED", "serialNumber": "56464646" }, "response": { "acquirerCode": "00", "acquirerMessage": "Approved", "gatewayCode": "APPROVED", "gatewayRecommendation": "PROCEED" }, "result": "SUCCESS", "sourceOfFunds": { "provided": { "card": { "brand": "MASTERCARD", "emvRequest": { "5F2A": "840", "5F34": "03", "82": "3000", "95": "0000008000", "9A": "191105", "9C": "00", "9F02": "000000002000", "9F10": "0210A5800F040400000000000000000000FF", "9F1A": "404", "9F26": "E4754D7F5695F63B", "9F27": "80", "9F33": "60B8C8", "9F34": "410302", "9F36": "0027", "9F37": "162D6807" }, "emvResponse": { "72": "9F180408041215860E04DA9F5809030691D72E6F027DC6", "91": "B7D5309D4B3E6CDB3030" }, "expiry": { "month": "12", "year": "25" }, "fundingMethod": "CREDIT", "number": "513333xxxxxx3338", "scheme": "MASTERCARD", "sequenceNumber": "003", "storedOnFile": "NOT_STORED" } }, "type": "CARD" }, "timeOfLastUpdate": "2025-07-23T07:22:26.389Z", "timeOfRecord": "2025-07-23T07:22:26.238Z", "transaction": { "acquirer": { "batch": 20250723, "date": "0723", "id": "CYG_TESTACQ_S2I", "merchantId": "9808", "transactionId": "401655599" }, "amount": 20.00, "authenticationStatus": "AUTHENTICATION_NOT_IN_EFFECT", "authorizationCode": "112233", "currency": "USD", "id": "AKS_171768015", "receipt": "520407142118", "source": "CARD_PRESENT", "stan": "142118", "terminal": "0002", "type": "AUTHORIZATION" }, "version": "100" } ``` ### Capture {#capture} | HTTP Method | URL | |-------------|------------------------------------------------------------------------------------------------------------------| | PUT | https://{{host}}/api/rest/version/latest/merchant/CYG_S2I_MER2/order/{{order_id}}/transaction/{{transaction_id}} | ```json { "apiOperation": "CAPTURE", "transaction": { "amount": "20", "currency": "USD" } } ``` ```json { "authorizationResponse": { "commercialCard": "123", "commercialCardIndicator": "1", "date": "0723", "financialNetworkCode": "MCC", "posData": "0000004000900", "posEntryMode": "051", "processingCode": "003000", "responseCode": "00", "stan": "142118", "time": "072226", "transactionIdentifier": "401655599", "transactionIntegrityClass": "A1" }, "gatewayEntryPoint": "WEB_SERVICES_API", "merchant": "CYG_S2I_MER2", "order": { "amount": 20.00, "certainty": "FINAL", "chargeback": { "amount": 0, "currency": "USD" }, "creationTime": "2025-07-23T07:22:26.209Z", "currency": "USD", "id": "AKS_442597558", "lastUpdatedTime": "2025-07-23T07:23:18.974Z", "merchantAmount": 20.00, "merchantCategoryCode": "4111", "merchantCurrency": "USD", "status": "CAPTURED", "totalAuthorizedAmount": 20.00, "totalCapturedAmount": 20.00, "totalDisbursedAmount": 0.00, "totalRefundedAmount": 0.00 }, "posTerminal": { "address": { "country": "AUS", "postcodeZip": "5000" }, "attended": "ATTENDED", "cardPresenceCapability": "CARD_PRESENT", "cardholderActivated": "NOT_CARDHOLDER_ACTIVATED", "inputCapability": "CHIP", "lane": "Lane_03", "location": "MERCHANT_TERMINAL_ON_PREMISES", "onlineReasonCode": "FORCED_BY_MERCHANT", "panEntryMode": "CHIP", "pinEntryCapability": "OFFLINE_PIN_ONLY", "serialNumber": "56464646" }, "response": { "acquirerCode": "00", "acquirerMessage": "Approved", "gatewayCode": "APPROVED" }, "result": "SUCCESS", "sourceOfFunds": { "provided": { "card": { "brand": "MASTERCARD", "expiry": { "month": "12", "year": "25" }, "fundingMethod": "CREDIT", "number": "513333xxxxxx3338", "scheme": "MASTERCARD", "sequenceNumber": "003", "storedOnFile": "NOT_STORED" } }, "type": "CARD" }, "timeOfLastUpdate": "2025-07-23T07:23:18.974Z", "timeOfRecord": "2025-07-23T07:23:18.915Z", "transaction": { "acquirer": { "batch": 20250723, "date": "0723", "id": "CYG_TESTACQ_S2I", "merchantId": "9808", "settlementDate": "2025-07-23", "timeZone": "+1000", "transactionId": "401655599" }, "amount": 20.00, "authorizationCode": "112233", "currency": "USD", "id": "AKS_778115216", "receipt": "520407142118", "source": "CARD_PRESENT", "stan": "143198", "terminal": "0002", "type": "CAPTURE" }, "version": "100" } ``` ### Pay {#pay} | HTTP Method | URL | |-------------|------------------------------------------------------------------------------------------------------------------| | PUT | https://{{host}}/api/rest/version/latest/merchant/CYG_S2I_MER1/order/{{order_id}}/transaction/{{transaction_id}} | ```json { "apiOperation": "PAY", "order": { "amount": "20", "currency": "USD" }, "transaction": { "source": "CARD_PRESENT" }, "sourceOfFunds": { "type": "CARD", "provided": { "card": { "number": "5133333333333338", "expiry": { "month": "12", "year": "25" }, "emvRequest": { "5F34": "03", "82": "3000", "95": "0000008000", "9F02": "000000002000", "9A": "191105", "5F2A": "840", "9F1A": "404", "9F10": "0210A5800F040400000000000000000000FF", "9F34": "410302", "9F36": "0027", "9C": "00", "9F26": "E4754D7F5695F63B", "9F27": "80", "9F37": "162D6807", "9F33": "60B8C8" }, "sequenceNumber": "003" } } }, "posTerminal": { "address": { "country": "AUS", "postcodeZip": "5000" }, "inputCapability": "CHIP", "panEntryMode": "CHIP", "pinEntryCapability": "OFFLINE_PIN_ONLY", "location": "MERCHANT_TERMINAL_ON_PREMISES", "lane": "Lane_03", "attended": "ATTENDED", "serialNumber": "56464646", "onlineReasonCode": "FORCED_BY_MERCHANT", "cardPresenceCapability": "CARD_PRESENT", "cardholderActivated": "NOT_CARDHOLDER_ACTIVATED" } } ``` ```json { "authorizationResponse": { "commercialCard": "123", "commercialCardIndicator": "1", "date": "0723", "financialNetworkCode": "MCC", "posData": "0000000000900", "posEntryMode": "051", "processingCode": "003000", "responseCode": "00", "stan": "145278", "time": "072557", "transactionIdentifier": "191468178", "transactionIntegrityClass": "A1" }, "gatewayEntryPoint": "WEB_SERVICES_API", "merchant": "CYG_S2I_MER2", "order": { "amount": 20.00, "authenticationStatus": "AUTHENTICATION_NOT_IN_EFFECT", "chargeback": { "amount": 0, "currency": "USD" }, "creationTime": "2025-07-23T07:25:57.560Z", "currency": "USD", "id": "AKS_732797750", "lastUpdatedTime": "2025-07-23T07:25:57.754Z", "merchantAmount": 20.00, "merchantCategoryCode": "4111", "merchantCurrency": "USD", "status": "CAPTURED", "totalAuthorizedAmount": 20.00, "totalCapturedAmount": 20.00, "totalDisbursedAmount": 0.00, "totalRefundedAmount": 0.00 }, "posTerminal": { "address": { "country": "AUS", "postcodeZip": "5000" }, "attended": "ATTENDED", "cardPresenceCapability": "CARD_PRESENT", "cardholderActivated": "NOT_CARDHOLDER_ACTIVATED", "inputCapability": "CHIP", "lane": "Lane_03", "location": "MERCHANT_TERMINAL_ON_PREMISES", "onlineReasonCode": "FORCED_BY_MERCHANT", "panEntryMode": "CHIP", "pinEntryCapability": "OFFLINE_PIN_ONLY", "serialNumber": "56464646" }, "response": { "acquirerCode": "00", "acquirerMessage": "Approved", "gatewayCode": "APPROVED", "gatewayRecommendation": "PROCEED" }, "result": "SUCCESS", "sourceOfFunds": { "provided": { "card": { "brand": "MASTERCARD", "expiry": { "month": "12", "year": "25" }, "fundingMethod": "CREDIT", "number": "513333xxxxxx3338", "scheme": "MASTERCARD", "sequenceNumber": "003", "storedOnFile": "NOT_STORED" } }, "type": "CARD" }, "timeOfLastUpdate": "2025-07-23T07:25:57.754Z", "timeOfRecord": "2025-07-23T07:25:57.602Z", "transaction": { "acquirer": { "batch": 20250723, "date": "0723", "id": "CYG_TESTACQ_S2I", "merchantId": "9808", "settlementDate": "2025-07-23", "timeZone": "+1000", "transactionId": "191468178" }, "amount": 20.00, "authenticationStatus": "AUTHENTICATION_NOT_IN_EFFECT", "authorizationCode": "112233", "currency": "USD", "id": "AKS_551568960", "receipt": "520407145278", "source": "CARD_PRESENT", "stan": "145278", "terminal": "0001", "type": "PAYMENT" }, "version": "100" } ``` ### Refund {#refund} | HTTP Method | URL | |-------------|------------------------------------------------------------------------------------------------------------------| | PUT | https://{{host}}/api/rest/version/latest/merchant/CYG_S2I_MER2/order/{{order_id}}/transaction/{{transaction_id}} | ```json { "apiOperation": "REFUND", "transaction": { "amount": "20", "currency": "USD" } } ``` ```json { "authorizationResponse": { "commercialCard": "123", "commercialCardIndicator": "1", "date": "0723", "financialNetworkCode": "MCC", "posData": "0000004000900", "posEntryMode": "051", "processingCode": "203000", "responseCode": "00", "stan": "142118", "time": "072226", "transactionIdentifier": "401655599", "transactionIntegrityClass": "A1" }, "gatewayEntryPoint": "WEB_SERVICES_API", "merchant": "CYG_S2I_MER2", "order": { "amount": 20.00, "certainty": "FINAL", "chargeback": { "amount": 0, "currency": "USD" }, "creationTime": "2025-07-23T07:22:26.209Z", "currency": "USD", "id": "AKS_442597558", "lastUpdatedTime": "2025-07-23T07:25:22.948Z", "merchantAmount": 20.00, "merchantCategoryCode": "4111", "merchantCurrency": "USD", "status": "REFUNDED", "totalAuthorizedAmount": 20.00, "totalCapturedAmount": 20.00, "totalDisbursedAmount": 0.00, "totalRefundedAmount": 20.00 }, "posTerminal": { "address": { "country": "AUS", "postcodeZip": "5000" }, "attended": "ATTENDED", "cardPresenceCapability": "CARD_PRESENT", "cardholderActivated": "NOT_CARDHOLDER_ACTIVATED", "inputCapability": "CHIP", "lane": "Lane_03", "location": "MERCHANT_TERMINAL_ON_PREMISES", "onlineReasonCode": "FORCED_BY_MERCHANT", "panEntryMode": "CHIP", "pinEntryCapability": "OFFLINE_PIN_ONLY", "serialNumber": "56464646" }, "response": { "acquirerCode": "00", "acquirerMessage": "Approved", "gatewayCode": "APPROVED" }, "result": "SUCCESS", "sourceOfFunds": { "provided": { "card": { "brand": "MASTERCARD", "expiry": { "month": "12", "year": "25" }, "fundingMethod": "CREDIT", "number": "513333xxxxxx3338", "scheme": "MASTERCARD", "sequenceNumber": "003", "storedOnFile": "NOT_STORED" } }, "type": "CARD" }, "timeOfLastUpdate": "2025-07-23T07:25:22.948Z", "timeOfRecord": "2025-07-23T07:25:22.900Z", "transaction": { "acquirer": { "batch": 20250723, "date": "0723", "id": "CYG_TESTACQ_S2I", "merchantId": "9808", "settlementDate": "2025-07-23", "timeZone": "+1000", "transactionId": "401655599" }, "amount": 20.00, "authorizationCode": "112233", "currency": "USD", "id": "AKS_864957872", "receipt": "520407144198", "source": "CARD_PRESENT", "stan": "144198", "terminal": "0002", "type": "REFUND" }, "version": "100" } ``` ### Examples of Tap on Phone with online pin {#examples-of-tap-on-phone-with-online-pin} ### Mastercard {#mastercard} ### Authorize {#authorize} | HTTP Method | URL | |-------------|------------------------------------------------------------------------------------------------------------| | PUT | https://{{host}}/api/rest/version/latest/merchant/{merchantId}/order/{orderid}/transaction/{transactionid} | ```json { "apiOperation": "AUTHORIZE", "order": { "amount": "113.00", "currency": "AUD" }, "posTerminal": { "address": { "country": "AUS", "postcodeZip": "4000" }, "attended": "ATTENDED", "cardPresenceCapability": "CARD_PRESENT", "cardholderActivated": "MPOS_ACCEPTANCE_DEVICE", "inputCapability": "CONTACTLESS_CHIP", "lane": "teapost", "location": "MERCHANT_TERMINAL_ON_PREMISES", "panEntryMode": "CONTACTLESS", "pinLengthCapability": "6", "pinEntryCapability": "PIN_SUPPORTED", "mobile": { "cardInputDevice": "BUILT_IN" } }, "sourceOfFunds": { "provided": { "card": { "emvRequest": { "5A": "5123456789012346", "5F2A": "840", "82": "0000", "84": "010101010101", "95": "0000000000", "9A": "161021", "9B": "0101", "9C": "00", "9F02": "000000001099", "9F03": "000000000000", "9F06": "010101010101", "9F07": "0101", "9F09": "0101", "9F10": "06011103A000000A0100000000000BB0ABAD", "9F1A": "840", "9F1E": "0123ABCD", "9F26": "D1F722D47FCA8273", "9F27": "40", "9F33": "E0B8C8", "9F34": "1E0300", "9F35": "12", "9F36": "0002", "9F37": "2A4E1690", "9F41": "0123", "9F53": "A", "9F6E": "0101" }, "expiry": { "month": "05", "year": "21" }, "pin": { "encryptionState": "VALID", "initializationVector": "1000000000000000", "keySerialNumber": "FFFF0000000004100499", "payload": "506ADB1C44FACBDE" }, "number": "5123456789012346", "sequenceNumber": "099" } }, "type": "CARD" }, "transaction": { "source": "CARD_PRESENT" } } ``` ```json { "authorizationResponse": { "commercialCard": "123", "commercialCardIndicator": "1", "date": "0605", "financialNetworkCode": "MCC", "posData": "0000004009300", "posEntryMode": "071", "processingCode": "003000", "responseCode": "00", "stan": "46239", "time": "090308", "transactionIdentifier": "856918159", "transactionIntegrityClass": "A1" }, "gatewayEntryPoint": "WEB_SERVICES_API", "merchant": "CYG_S2I_MER2", "order": { "amount": 113.00, "authenticationStatus": "AUTHENTICATION_NOT_IN_EFFECT", "certainty": "FINAL", "chargeback": { "amount": 0, "currency": "AUD" }, "creationTime": "2022-06-05T09:03:08.551Z", "currency": "AUD", "id": "498716163", "lastUpdatedTime": "2022-06-05T09:03:08.706Z", "merchantAmount": 113.00, "merchantCategoryCode": "4111", "merchantCurrency": "AUD", "status": "AUTHORIZED", "totalAuthorizedAmount": 113.00, "totalCapturedAmount": 0.00, "totalDisbursedAmount": 0.00, "totalRefundedAmount": 0.00 }, "posTerminal": { "address": { "country": "AUS", "postcodeZip": "4000" }, "attended": "ATTENDED", "cardPresenceCapability": "CARD_PRESENT", "cardholderActivated": "MPOS_ACCEPTANCE_DEVICE", "inputCapability": "CONTACTLESS_CHIP", "lane": "teapost", "location": "MERCHANT_TERMINAL_ON_PREMISES", "mobile": { "cardInputDevice": "BUILT_IN" }, "panEntryMode": "CONTACTLESS", "pinEntryCapability": "PIN_SUPPORTED", "pinLengthCapability": 6, "serialNumber": "0123ABCD" }, "response": { "acquirerCode": "00", "acquirerMessage": "Approved", "gatewayCode": "APPROVED", "gatewayRecommendation": "NO_ACTION" }, "result": "SUCCESS", "sourceOfFunds": { "provided": { "card": { "brand": "MASTERCARD", "emvRequest": { "5F2A": "840", "82": "0000", "84": "010101010101", "95": "0000000000", "9A": "161021", "9B": "0101", "9C": "00", "9F02": "000000001099", "9F03": "000000000000", "9F06": "010101010101", "9F07": "0101", "9F09": "0101", "9F10": "06011103A000000A0100000000000BB0ABAD", "9F1A": "840", "9F1E": "0123ABCD", "9F26": "D1F722D47FCA8273", "9F27": "40", "9F33": "E0B8C8", "9F34": "1E0300", "9F35": "12", "9F36": "0002", "9F37": "2A4E1690", "9F41": "0123", "9F53": "A", "9F6E": "0101" }, "emvResponse": { "72": "9F180408041215860E04DA9F5809030691D72E6F027DC6", "91": "B7D5309D4B3E6CDB3030" }, "expiry": { "month": "5", "year": "21" }, "fundingMethod": "CREDIT", "number": "512345xxxxxx2346", "pin": { "encryptionState": "VALID", "keySerialNumber": "FFFF0000000004100499" }, "scheme": "MASTERCARD", "sequenceNumber": "099", "storedOnFile": "NOT_STORED" } }, "type": "CARD" }, "timeOfLastUpdate": "2022-06-05T09:03:08.706Z", "timeOfRecord": "2022-06-05T09:03:08.595Z", "transaction": { "acquirer": { "batch": 20220605, "date": "0605", "id": "CYG_TESTACQ_S2I", "merchantId": "9808", "transactionId": "856918159" }, "amount": 113.00, "authenticationStatus": "AUTHENTICATION_NOT_IN_EFFECT", "authorizationCode": "112233", "currency": "AUD", "id": "864331019", "receipt": "215609046239", "source": "CARD_PRESENT", "stan": "46239", "terminal": "0002", "type": "AUTHORIZATION" }, "version": "66" } ``` ### Capture {#capture-1} | HTTP Method | URL | |-------------|------------------------------------------------------------------------------------------------------------| | PUT | https://{{host}}/api/rest/version/latest/merchant/{merchantId}/order/{orderid}/transaction/{transactionid} | ```json { "apiOperation": "CAPTURE", "transaction": { "amount": "113.00", "currency": "AUD" } } ``` ```json { "authorizationResponse": { "commercialCard": "123", "commercialCardIndicator": "1", "date": "0605", "financialNetworkCode": "MCC", "posData": "0000004009300", "posEntryMode": "071", "processingCode": "003000", "responseCode": "00", "stan": "46239", "time": "090308", "transactionIdentifier": "856918159", "transactionIntegrityClass": "A1" }, "gatewayEntryPoint": "WEB_SERVICES_API", "merchant": "CYG_S2I_MER2", "order": { "amount": 113.00, "certainty": "FINAL", "chargeback": { "amount": 0, "currency": "AUD" }, "creationTime": "2022-06-05T09:03:08.551Z", "currency": "AUD", "id": "498716163", "lastUpdatedTime": "2022-06-05T09:03:13.374Z", "merchantAmount": 113.00, "merchantCategoryCode": "4111", "merchantCurrency": "AUD", "status": "CAPTURED", "totalAuthorizedAmount": 113.00, "totalCapturedAmount": 113.00, "totalDisbursedAmount": 0.00, "totalRefundedAmount": 0.00 }, "posTerminal": { "address": { "country": "AUS", "postcodeZip": "4000" }, "attended": "ATTENDED", "cardPresenceCapability": "CARD_PRESENT", "cardholderActivated": "MPOS_ACCEPTANCE_DEVICE", "inputCapability": "CONTACTLESS_CHIP", "lane": "teapost", "location": "MERCHANT_TERMINAL_ON_PREMISES", "mobile": { "cardInputDevice": "BUILT_IN" }, "panEntryMode": "CONTACTLESS", "pinEntryCapability": "PIN_SUPPORTED", "pinLengthCapability": 6, "serialNumber": "0123ABCD" }, "response": { "acquirerCode": "00", "acquirerMessage": "Approved", "gatewayCode": "APPROVED" }, "result": "SUCCESS", "sourceOfFunds": { "provided": { "card": { "brand": "MASTERCARD", "expiry": { "month": "5", "year": "21" }, "fundingMethod": "CREDIT", "number": "512345xxxxxx2346", "scheme": "MASTERCARD", "sequenceNumber": "099", "storedOnFile": "NOT_STORED" } }, "type": "CARD" }, "timeOfLastUpdate": "2022-06-05T09:03:13.374Z", "timeOfRecord": "2022-06-05T09:03:13.351Z", "transaction": { "acquirer": { "batch": 20220605, "date": "0605", "id": "CYG_TESTACQ_S2I", "merchantId": "9808", "settlementDate": "2022-06-05", "timeZone": "+1000", "transactionId": "856918159" }, "amount": 113.00, "authorizationCode": "112233", "currency": "AUD", "id": "329521387", "receipt": "215609046239", "source": "CARD_PRESENT", "stan": "47269", "terminal": "0002", "type": "CAPTURE" }, "version": "66" } ``` ### Refund {#refund-1} | HTTP Method | URL | |-------------|------------------------------------------------------------------------------------------------------------| | PUT | https://{{host}}/api/rest/version/latest/merchant/{merchantId}/order/{orderid}/transaction/{transactionid} | ```json { "apiOperation": "REFUND", "transaction": { "amount": "113", "currency": "AUD" } } ``` ```json { "authorizationResponse": { "commercialCard": "123", "commercialCardIndicator": "1", "date": "0605", "financialNetworkCode": "MCC", "posData": "0000004009300", "posEntryMode": "071", "processingCode": "203000", "responseCode": "00", "stan": "46239", "time": "090308", "transactionIdentifier": "856918159", "transactionIntegrityClass": "A1" }, "gatewayEntryPoint": "WEB_SERVICES_API", "merchant": "CYG_S2I_MER2", "order": { "amount": 113.00, "certainty": "FINAL", "chargeback": { "amount": 0, "currency": "AUD" }, "creationTime": "2022-06-05T09:03:08.551Z", "currency": "AUD", "id": "498716163", "lastUpdatedTime": "2022-06-05T09:03:17.384Z", "merchantAmount": 113.00, "merchantCategoryCode": "4111", "merchantCurrency": "AUD", "status": "REFUNDED", "totalAuthorizedAmount": 113.00, "totalCapturedAmount": 113.00, "totalDisbursedAmount": 0.00, "totalRefundedAmount": 113.00 }, "posTerminal": { "address": { "country": "AUS", "postcodeZip": "4000" }, "attended": "ATTENDED", "cardPresenceCapability": "CARD_PRESENT", "cardholderActivated": "MPOS_ACCEPTANCE_DEVICE", "inputCapability": "CONTACTLESS_CHIP", "lane": "teapost", "location": "MERCHANT_TERMINAL_ON_PREMISES", "mobile": { "cardInputDevice": "BUILT_IN" }, "panEntryMode": "CONTACTLESS", "pinEntryCapability": "PIN_SUPPORTED", "pinLengthCapability": 6, "serialNumber": "0123ABCD" }, "response": { "acquirerCode": "00", "acquirerMessage": "Approved", "gatewayCode": "APPROVED" }, "result": "SUCCESS", "sourceOfFunds": { "provided": { "card": { "brand": "MASTERCARD", "expiry": { "month": "5", "year": "21" }, "fundingMethod": "CREDIT", "number": "512345xxxxxx2346", "scheme": "MASTERCARD", "sequenceNumber": "099", "storedOnFile": "NOT_STORED" } }, "type": "CARD" }, "timeOfLastUpdate": "2022-06-05T09:03:17.384Z", "timeOfRecord": "2022-06-05T09:03:17.356Z", "transaction": { "acquirer": { "batch": 20220605, "date": "0605", "id": "CYG_TESTACQ_S2I", "merchantId": "9808", "settlementDate": "2022-06-05", "timeZone": "+1000", "transactionId": "856918159" }, "amount": 113.00, "authorizationCode": "112233", "currency": "AUD", "id": "279684275", "receipt": "215609048289", "source": "CARD_PRESENT", "stan": "48289", "terminal": "0002", "type": "REFUND" }, "version": "66" } ``` ### Pay {#pay-1} | HTTP Method | URL | |-------------|------------------------------------------------------------------------------------------------------------| | PUT | https://{{host}}/api/rest/version/latest/merchant/{merchantId}/order/{orderid}/transaction/{transactionid} | ```json { "apiOperation": "PAY", "order": { "amount": "100.00", "currency": "AUD" }, "posTerminal": { "address": { "country": "AUS", "postcodeZip": "4000" }, "attended": "ATTENDED", "cardPresenceCapability": "CARD_PRESENT", "cardholderActivated": "MPOS_ACCEPTANCE_DEVICE", "inputCapability": "CONTACTLESS_CHIP", "lane": "teapost", "location": "MERCHANT_TERMINAL_ON_PREMISES", "panEntryMode": "CONTACTLESS", "pinLengthCapability": "6", "pinEntryCapability": "PIN_SUPPORTED", "mobile": { "cardInputDevice": "BUILT_IN" } }, "sourceOfFunds": { "provided": { "card": { "emvRequest": { "82": "5C00", "84": "A0000000031010034761739000000000", "95": "0000262144", "9A": "210209", "9B": "0000", "9C": "00", "5F2A": "036", "5F34": "00", "9F02": "000000003100", "9F03": "000000000000", "9F10": "06020103A02000", "9F1A": "036", "9F1E": "2BC7A55C", "9F6E": "00560000313400", "9F26": "51B579DE8D55E180", "9F27": "80", "9F33": "60F0C8", "9F34": "000000", "9F36": "0201", "9F37": "6388675D" }, "expiry": { "month": "12", "year": "24" }, "pin": { "encryptionState": "VALID", "keySerialNumber": "FFFF0000000004100499", "payload": "506ADB1C44FACBDE" }, "track2": "5123456789012346=241220116006711" } }, "type": "CARD" }, "transaction": { "source": "CARD_PRESENT" } } ``` ```json { "authorizationResponse": { "commercialCardIndicator": "1", "date": "0913", "financialNetworkCode": "MCC", "financialNetworkDate": "2022-09-12", "posData": "0000000009300", "posEntryMode": "071", "processingCode": "000000", "responseCode": "00", "stan": "172004", "time": "034348", "transactionIdentifier": "U6MJE8" }, "gatewayEntryPoint": "WEB_SERVICES_API", "merchant": "MTFCYGNUS01", "order": { "amount": 100.00, "authenticationStatus": "AUTHENTICATION_NOT_IN_EFFECT", "chargeback": { "amount": 0, "currency": "AUD" }, "creationTime": "2022-09-13T03:43:48.298Z", "currency": "AUD", "id": "97712284", "lastUpdatedTime": "2022-09-13T03:43:48.677Z", "merchantAmount": 100.00, "merchantCategoryCode": "4111", "merchantCurrency": "AUD", "status": "CAPTURED", "totalAuthorizedAmount": 100.00, "totalCapturedAmount": 100.00, "totalDisbursedAmount": 0.00, "totalRefundedAmount": 0.00 }, "posTerminal": { "address": { "country": "AUS", "postcodeZip": "4000" }, "attended": "ATTENDED", "cardPresenceCapability": "CARD_PRESENT", "cardholderActivated": "MPOS_ACCEPTANCE_DEVICE", "inputCapability": "CONTACTLESS_CHIP", "lane": "teapost", "location": "MERCHANT_TERMINAL_ON_PREMISES", "mobile": { "cardInputDevice": "BUILT_IN" }, "panEntryMode": "CONTACTLESS", "pinEntryCapability": "PIN_SUPPORTED", "pinLengthCapability": 6, "serialNumber": "2BC7A55C" }, "response": { "acquirerCode": "00", "acquirerMessage": "Approved", "gatewayCode": "APPROVED", "gatewayRecommendation": "NO_ACTION" }, "result": "SUCCESS", "sourceOfFunds": { "provided": { "card": { "brand": "MASTERCARD", "emvRequest": { "5F2A": "036", "5F34": "00", "82": "5C00", "84": "A0000000031010034761739000000000", "95": "0000262144", "9A": "210209", "9B": "0000", "9C": "00", "9F02": "000000003100", "9F03": "000000000000", "9F10": "06020103A02000", "9F1A": "036", "9F1E": "2BC7A55C", "9F26": "51B579DE8D55E180", "9F27": "80", "9F33": "60F0C8", "9F34": "000000", "9F36": "0201", "9F37": "6388675D", "9F6E": "00560000313400" }, "expiry": { "month": "12", "year": "24" }, "fundingMethod": "CREDIT", "number": "512345xxxxxx2346", "pin": { "encryptionState": "VALID", "keySerialNumber": "FFFF0000000004100499" }, "scheme": "MASTERCARD", "sequenceNumber": "00", "storedOnFile": "NOT_STORED", "trackDataProvided": true } }, "type": "CARD" }, "timeOfLastUpdate": "2022-09-13T03:43:48.677Z", "timeOfRecord": "2022-09-13T03:43:48.330Z", "transaction": { "acquirer": { "batch": 20220913, "date": "0913", "id": "CYG_TESTACQ_S2I", "merchantId": "123456", "settlementDate": "2022-09-13", "timeZone": "+1000", "transactionId": "U6MJE8" }, "amount": 100.00, "authenticationStatus": "AUTHENTICATION_NOT_IN_EFFECT", "authorizationCode": "318450", "currency": "AUD", "id": "862233747", "receipt": "225603172004", "source": "CARD_PRESENT", "stan": "172004", "terminal": "0001", "type": "PAYMENT" }, "version": "67" } ``` ### Visa {#visa} ### Authorize {#authorize-1} | HTTP Method | URL | |-------------|------------------------------------------------------------------------------------------------------------| | PUT | https://{{host}}/api/rest/version/latest/merchant/{merchantId}/order/{orderid}/transaction/{transactionid} | ```json { "apiOperation": "AUTHORIZE", "order": { "amount": "113.00", "currency": "AUD" }, "posTerminal": { "address": { "country": "AUS", "postcodeZip": "4000" }, "attended": "ATTENDED", "cardPresenceCapability": "CARD_PRESENT", "cardholderActivated": "MPOS_ACCEPTANCE_DEVICE", "inputCapability": "CONTACTLESS_CHIP", "lane": "teapost", "location": "MERCHANT_TERMINAL_ON_PREMISES", "panEntryMode": "CONTACTLESS", "pinLengthCapability": "6", "pinEntryCapability": "PIN_SUPPORTED", "mobile": { "cardInputDevice": "BUILT_IN" } }, "sourceOfFunds": { "provided": { "card": { "emvRequest": { "5A": "4909654321012344", "5F2A": "840", "82": "0000", "84": "010101010101", "95": "0000000000", "9A": "161021", "9B": "0101", "9C": "00", "9F02": "000000001099", "9F03": "000000000000", "9F06": "010101010101", "9F07": "0101", "9F09": "0101", "9F10": "06011103A000000A0100000000000BB0ABAD", "9F1A": "840", "9F1E": "0123ABCD", "9F26": "D1F722D47FCA8273", "9F27": "40", "9F33": "E0B8C8", "9F34": "1E0300", "9F35": "12", "9F36": "0002", "9F37": "2A4E1690", "9F41": "0123", "9F53": "A", "9F6E": "0101" }, "expiry": { "month": "01", "year": "39" }, "number": "4909654321012344", "pin": { "encryptionState": "VALID", "initializationVector": "1000000000000000", "keySerialNumber": "FFFF0000000004100499", "payload": "E2F7C05C626BBB24" }, "sequenceNumber": "099" } }, "type": "CARD" }, "transaction": { "source": "CARD_PRESENT" } } ``` ```json { "authorizationResponse": { "cardLevelIndicator": "XX", "commercialCard": "123", "commercialCardIndicator": "1", "date": "0606", "marketSpecificData": "A", "posData": "0000004009400", "posEntryMode": "071", "processingCode": "003000", "responseCode": "00", "returnAci": "Y", "stan": "14434", "time": "030806", "transactionIdentifier": "228415442029923" }, "gatewayEntryPoint": "WEB_SERVICES_API", "merchant": "CYG_S2I_MER2", "order": { "amount": 113.00, "authenticationStatus": "AUTHENTICATION_NOT_IN_EFFECT", "certainty": "FINAL", "chargeback": { "amount": 0, "currency": "AUD" }, "creationTime": "2022-06-06T03:08:06.678Z", "currency": "AUD", "id": "92441151", "lastUpdatedTime": "2022-06-06T03:08:06.922Z", "merchantAmount": 113.00, "merchantCategoryCode": "4111", "merchantCurrency": "AUD", "status": "AUTHORIZED", "totalAuthorizedAmount": 113.00, "totalCapturedAmount": 0.00, "totalDisbursedAmount": 0.00, "totalRefundedAmount": 0.00 }, "posTerminal": { "address": { "country": "AUS", "postcodeZip": "4000" }, "attended": "ATTENDED", "cardPresenceCapability": "CARD_PRESENT", "cardholderActivated": "MPOS_ACCEPTANCE_DEVICE", "inputCapability": "CONTACTLESS_CHIP", "lane": "teapost", "location": "MERCHANT_TERMINAL_ON_PREMISES", "mobile": { "cardInputDevice": "BUILT_IN" }, "panEntryMode": "CONTACTLESS", "pinEntryCapability": "PIN_SUPPORTED", "pinLengthCapability": 6, "serialNumber": "0123ABCD" }, "response": { "acquirerCode": "00", "acquirerMessage": "Approved", "gatewayCode": "APPROVED", "gatewayRecommendation": "NO_ACTION" }, "result": "SUCCESS", "sourceOfFunds": { "provided": { "card": { "brand": "VISA", "emvRequest": { "5F2A": "840", "82": "0000", "84": "010101010101", "95": "0000000000", "9A": "161021", "9B": "0101", "9C": "00", "9F02": "000000001099", "9F03": "000000000000", "9F06": "010101010101", "9F07": "0101", "9F09": "0101", "9F10": "06011103A000000A0100000000000BB0ABAD", "9F1A": "840", "9F1E": "0123ABCD", "9F26": "D1F722D47FCA8273", "9F27": "40", "9F33": "E0B8C8", "9F34": "1E0300", "9F35": "12", "9F36": "0002", "9F37": "2A4E1690", "9F41": "0123", "9F53": "A", "9F6E": "0101" }, "emvResponse": { "72": "9F180408041215860E04DA9F5809030691D72E6F027DC6", "91": "B7D5309D4B3E6CDB3030" }, "expiry": { "month": "1", "year": "39" }, "fundingMethod": "DEBIT", "number": "490965xxxxxx2344", "pin": { "encryptionState": "VALID", "keySerialNumber": "FFFF0000000004100499" }, "scheme": "VISA", "sequenceNumber": "099", "storedOnFile": "NOT_STORED" } }, "type": "CARD" }, "timeOfLastUpdate": "2022-06-06T03:08:06.922Z", "timeOfRecord": "2022-06-06T03:08:06.746Z", "transaction": { "acquirer": { "batch": 20220606, "date": "0606", "id": "CYG_TESTACQ_S2I", "merchantId": "9808", "transactionId": "228415442029923" }, "amount": 113.00, "authenticationStatus": "AUTHENTICATION_NOT_IN_EFFECT", "authorizationCode": "112233", "currency": "AUD", "id": "428298915", "receipt": "215703014434", "source": "CARD_PRESENT", "stan": "14434", "terminal": "0002", "type": "AUTHORIZATION" }, "version": "65" } ``` ### Capture {#capture-2} | HTTP Method | URL | |-------------|------------------------------------------------------------------------------------------------------------| | PUT | https://{{host}}/api/rest/version/latest/merchant/{merchantId}/order/{orderid}/transaction/{transactionid} | ```json { "apiOperation": "CAPTURE", "transaction": { "amount": "113.00", "currency": "AUD" } } ``` ```json { "authorizationResponse": { "cardLevelIndicator": "XX", "commercialCard": "123", "commercialCardIndicator": "1", "date": "0606", "marketSpecificData": "A", "posData": "0000004009400", "posEntryMode": "071", "processingCode": "003000", "responseCode": "00", "returnAci": "Y", "stan": "14434", "time": "030806", "transactionIdentifier": "228415442029923" }, "gatewayEntryPoint": "WEB_SERVICES_API", "merchant": "CYG_S2I_MER2", "order": { "amount": 113.00, "certainty": "FINAL", "chargeback": { "amount": 0, "currency": "AUD" }, "creationTime": "2022-06-06T03:08:06.678Z", "currency": "AUD", "id": "92441151", "lastUpdatedTime": "2022-06-06T03:08:33.350Z", "merchantAmount": 113.00, "merchantCategoryCode": "4111", "merchantCurrency": "AUD", "status": "CAPTURED", "totalAuthorizedAmount": 113.00, "totalCapturedAmount": 113.00, "totalDisbursedAmount": 0.00, "totalRefundedAmount": 0.00 }, "posTerminal": { "address": { "country": "AUS", "postcodeZip": "4000" }, "attended": "ATTENDED", "cardPresenceCapability": "CARD_PRESENT", "cardholderActivated": "MPOS_ACCEPTANCE_DEVICE", "inputCapability": "CONTACTLESS_CHIP", "lane": "teapost", "location": "MERCHANT_TERMINAL_ON_PREMISES", "mobile": { "cardInputDevice": "BUILT_IN" }, "panEntryMode": "CONTACTLESS", "pinEntryCapability": "PIN_SUPPORTED", "pinLengthCapability": 6, "serialNumber": "0123ABCD" }, "response": { "acquirerCode": "00", "acquirerMessage": "Approved", "gatewayCode": "APPROVED" }, "result": "SUCCESS", "sourceOfFunds": { "provided": { "card": { "brand": "VISA", "expiry": { "month": "1", "year": "39" }, "fundingMethod": "DEBIT", "number": "490965xxxxxx2344", "scheme": "VISA", "sequenceNumber": "099", "storedOnFile": "NOT_STORED" } }, "type": "CARD" }, "timeOfLastUpdate": "2022-06-06T03:08:33.350Z", "timeOfRecord": "2022-06-06T03:08:33.316Z", "transaction": { "acquirer": { "batch": 20220606, "date": "0606", "id": "CYG_TESTACQ_S2I", "merchantId": "9808", "settlementDate": "2022-06-06", "timeZone": "+1000", "transactionId": "228415442029923" }, "amount": 113.00, "authorizationCode": "112233", "currency": "AUD", "id": "808640929", "receipt": "215703014434", "source": "CARD_PRESENT", "stan": "15514", "terminal": "0002", "type": "CAPTURE" }, "version": "65" } ``` ### Refund {#refund-2} | HTTP Method | URL | |-------------|------------------------------------------------------------------------------------------------------------| | PUT | https://{{host}}/api/rest/version/latest/merchant/{merchantId}/order/{orderid}/transaction/{transactionid} | ```json { "apiOperation": "REFUND", "transaction": { "amount": "113", "currency": "AUD" } } ``` ```json { "authorizationResponse": { "cardLevelIndicator": "XX", "commercialCard": "123", "commercialCardIndicator": "1", "date": "0606", "marketSpecificData": "A", "posData": "0000004009400", "posEntryMode": "071", "processingCode": "203000", "responseCode": "00", "returnAci": "Y", "stan": "14434", "time": "030806", "transactionIdentifier": "228415442029923" }, "gatewayEntryPoint": "WEB_SERVICES_API", "merchant": "CYG_S2I_MER2", "order": { "amount": 113.00, "certainty": "FINAL", "chargeback": { "amount": 0, "currency": "AUD" }, "creationTime": "2022-06-06T03:08:06.678Z", "currency": "AUD", "id": "92441151", "lastUpdatedTime": "2022-06-06T03:08:41.968Z", "merchantAmount": 113.00, "merchantCategoryCode": "4111", "merchantCurrency": "AUD", "status": "REFUNDED", "totalAuthorizedAmount": 113.00, "totalCapturedAmount": 113.00, "totalDisbursedAmount": 0.00, "totalRefundedAmount": 113.00 }, "posTerminal": { "address": { "country": "AUS", "postcodeZip": "4000" }, "attended": "ATTENDED", "cardPresenceCapability": "CARD_PRESENT", "cardholderActivated": "MPOS_ACCEPTANCE_DEVICE", "inputCapability": "CONTACTLESS_CHIP", "lane": "teapost", "location": "MERCHANT_TERMINAL_ON_PREMISES", "mobile": { "cardInputDevice": "BUILT_IN" }, "panEntryMode": "CONTACTLESS", "pinEntryCapability": "PIN_SUPPORTED", "pinLengthCapability": 6, "serialNumber": "0123ABCD" }, "response": { "acquirerCode": "00", "acquirerMessage": "Approved", "gatewayCode": "APPROVED" }, "result": "SUCCESS", "sourceOfFunds": { "provided": { "card": { "brand": "VISA", "expiry": { "month": "1", "year": "39" }, "fundingMethod": "DEBIT", "number": "490965xxxxxx2344", "scheme": "VISA", "sequenceNumber": "099", "storedOnFile": "NOT_STORED" } }, "type": "CARD" }, "timeOfLastUpdate": "2022-06-06T03:08:41.968Z", "timeOfRecord": "2022-06-06T03:08:41.932Z", "transaction": { "acquirer": { "batch": 20220606, "date": "0606", "id": "CYG_TESTACQ_S2I", "merchantId": "9808", "settlementDate": "2022-06-06", "timeZone": "+1000", "transactionId": "228415442029923" }, "amount": 113.00, "authorizationCode": "112233", "currency": "AUD", "id": "729929676", "receipt": "215703016604", "source": "CARD_PRESENT", "stan": "16604", "terminal": "0002", "type": "REFUND" }, "version": "65" } ``` ### Pay {#pay-2} | HTTP Method | URL | |-------------|------------------------------------------------------------------------------------------------------------| | PUT | https://{{host}}/api/rest/version/latest/merchant/{merchantId}/order/{orderid}/transaction/{transactionid} | ```json { "apiOperation": "PAY", "order": { "amount": "115.00", "currency": "AUD" }, "posTerminal": { "address": { "country": "AUS", "postcodeZip": "4000" }, "attended": "ATTENDED", "cardPresenceCapability": "CARD_PRESENT", "cardholderActivated": "MPOS_ACCEPTANCE_DEVICE", "inputCapability": "CONTACTLESS_CHIP", "lane": "teapost", "location": "MERCHANT_TERMINAL_ON_PREMISES", "panEntryMode": "CONTACTLESS", "pinLengthCapability": "6", "pinEntryCapability": "PIN_SUPPORTED", "mobile": { "cardInputDevice": "BUILT_IN" } }, "sourceOfFunds": { "provided": { "card": { "emvRequest": { "5A": "4909654321012344", "5F2A": "840", "82": "0000", "84": "010101010101", "95": "0000000000", "9A": "161021", "9B": "0101", "9C": "00", "9F02": "000000001099", "9F03": "000000000000", "9F06": "010101010101", "9F07": "0101", "9F09": "0101", "9F10": "06011103A000000A0100000000000BB0ABAD", "9F1A": "840", "9F1E": "0123ABCD", "9F26": "D1F722D47FCA8273", "9F27": "40", "9F33": "E0B8C8", "9F34": "1E0300", "9F35": "12", "9F36": "0002", "9F37": "2A4E1690", "9F41": "0123", "9F53": "A", "9F6E": "0101" }, "expiry": { "month": "01", "year": "39" }, "pin": { "encryptionState": "VALID", "initializationVector": "1000000000000000", "keySerialNumber": "FFFF0000000004100499", "payload": "E2F7C05C626BBB24" }, "number": "4909654321012344", "sequenceNumber": "000" } }, "type": "CARD" }, "transaction": { "source": "CARD_PRESENT" } } ``` ```json { "authorizationResponse": { "cardLevelIndicator": "XX", "commercialCard": "123", "commercialCardIndicator": "1", "date": "0606", "marketSpecificData": "A", "posData": "0000000009400", "posEntryMode": "071", "processingCode": "003000", "responseCode": "00", "returnAci": "Y", "stan": "17654", "time": "030920", "transactionIdentifier": "866432189928564" }, "gatewayEntryPoint": "WEB_SERVICES_API", "merchant": "CYG_S2I_MER1", "order": { "amount": 115.00, "authenticationStatus": "AUTHENTICATION_NOT_IN_EFFECT", "chargeback": { "amount": 0, "currency": "AUD" }, "creationTime": "2022-06-06T03:09:20.016Z", "currency": "AUD", "id": "527220772", "lastUpdatedTime": "2022-06-06T03:09:20.327Z", "merchantAmount": 115.00, "merchantCategoryCode": "1234", "merchantCurrency": "AUD", "status": "CAPTURED", "totalAuthorizedAmount": 115.00, "totalCapturedAmount": 115.00, "totalDisbursedAmount": 0.00, "totalRefundedAmount": 0.00 }, "posTerminal": { "address": { "country": "AUS", "postcodeZip": "4000" }, "attended": "ATTENDED", "cardPresenceCapability": "CARD_PRESENT", "cardholderActivated": "MPOS_ACCEPTANCE_DEVICE", "inputCapability": "CONTACTLESS_CHIP", "lane": "teapost", "location": "MERCHANT_TERMINAL_ON_PREMISES", "mobile": { "cardInputDevice": "BUILT_IN" }, "panEntryMode": "CONTACTLESS", "pinEntryCapability": "PIN_SUPPORTED", "pinLengthCapability": 6 }, "response": { "acquirerCode": "00", "acquirerMessage": "Approved", "gatewayCode": "APPROVED", "gatewayRecommendation": "NO_ACTION" }, "result": "SUCCESS", "sourceOfFunds": { "provided": { "card": { "brand": "VISA", "emvRequest": { "5F2A": "840", "82": "0000", "84": "010101010101", "95": "0000000000", "9A": "161021", "9B": "0101", "9C": "00", "9F02": "000000001099", "9F03": "000000000000", "9F06": "010101010101", "9F07": "0101", "9F09": "0101", "9F10": "06011103A000000A0100000000000BB0ABAD", "9F1A": "840", "9F1E": "0123ABCD", "9F26": "D1F722D47FCA8273", "9F27": "40", "9F33": "E0B8C8", "9F34": "1E0300", "9F35": "12", "9F36": "0002", "9F37": "2A4E1690", "9F41": "0123", "9F53": "A", "9F6E": "0101" }, "emvResponse": { "72": "9F180408041215860E04DA9F5809030691D72E6F027DC6", "91": "B7D5309D4B3E6CDB3030" }, "expiry": { "month": "1", "year": "39" }, "fundingMethod": "DEBIT", "number": "490965xxxxxx2344", "pin": { "encryptionState": "VALID", "keySerialNumber": "FFFF0000000004100499" }, "scheme": "VISA", "sequenceNumber": "000", "storedOnFile": "NOT_STORED" } }, "type": "CARD" }, "timeOfLastUpdate": "2022-06-06T03:09:20.327Z", "timeOfRecord": "2022-06-06T03:09:20.090Z", "transaction": { "acquirer": { "batch": 20220606, "date": "0606", "id": "CYG_TESTACQ_S2I", "merchantId": "9808", "settlementDate": "2022-06-06", "timeZone": "+1000", "transactionId": "866432189928564" }, "amount": 115.00, "authenticationStatus": "AUTHENTICATION_NOT_IN_EFFECT", "authorizationCode": "112233", "currency": "AUD", "id": "180385602", "receipt": "215703017654", "source": "CARD_PRESENT", "stan": "17654", "terminal": "0001", "type": "PAYMENT" }, "version": "65" } ``` ### American Express {#american-express} ### Authorize {#authorize-2} | HTTP Method | URL | |-------------|------------------------------------------------------------------------------------------------------------| | PUT | https://{{host}}/api/rest/version/latest/merchant/{merchantId}/order/{orderid}/transaction/{transactionid} | ```json { "apiOperation": "AUTHORIZE", "order": { "amount": "100.00", "currency": "AUD" }, "posTerminal": { "address": { "country": "AUS", "postcodeZip": "4000" }, "mobile": { "cardInputDevice": "INTEGRATED_DONGLE" }, "attended": "ATTENDED", "cardPresenceCapability": "CARD_PRESENT", "cardholderActivated": "MPOS_ACCEPTANCE_DEVICE", "inputCapability": "CONTACTLESS_CHIP", "lane": "teapost", "location": "MERCHANT_TERMINAL_ON_PREMISES", "panEntryMode": "CONTACTLESS", "pinLengthCapability": "6", "pinEntryCapability": "PIN_SUPPORTED" }, "sourceOfFunds": { "provided": { "card": { "emvRequest": { "5A": "345678901234564", "5F2A": "840", "5F24": "230603", "82": "0000", "84": "010101010101", "95": "0000000000", "9A": "161021", "9B": "0101", "9C": "00", "9F02": "000000001099", "9F03": "000000000000", "9F06": "010101010101", "9F07": "0101", "9F09": "0101", "9F10": "06011103A000000A0100000000000BB0ABAD", "9F1A": "840", "9F1E": "0123ABCD", "9F26": "D1F722D47FCA8273", "9F27": "40", "9F33": "E0B8C8", "9F34": "1E0300", "9F35": "12", "9F36": "0002", "9F37": "2A4E1690", "9F41": "0123", "9F53": "A", "9F6E": "0101" }, "expiry": { "month": "12", "year": "24" }, "pin": { "encryptionState": "VALID", "initializationVector": "1000000000000000", "keySerialNumber": "FFFF0000000004100499", "payload": "506ADB1C44FACBDE" }, "sequenceNumber": "000", "number": 345678901234564, "track2": "345678901234564=241220116006711" } }, "type": "CARD" }, "transaction": { "source": "CARD_PRESENT" } } ``` ```json { "authorizationResponse": { "date": "0607", "posData": "0000004009300", "posEntryMode": "071", "processingCode": "003000", "responseCode": "00", "stan": "27151", "time": "090124", "transactionIdentifier": "329712639801756" }, "gatewayEntryPoint": "WEB_SERVICES_API", "merchant": "CYG_S2I_MER2", "order": { "amount": 100.00, "authenticationStatus": "AUTHENTICATION_NOT_IN_EFFECT", "certainty": "FINAL", "chargeback": { "amount": 0, "currency": "AUD" }, "creationTime": "2022-06-07T09:01:24.028Z", "currency": "AUD", "id": "29796554", "lastUpdatedTime": "2022-06-07T09:01:24.197Z", "merchantAmount": 100.00, "merchantCategoryCode": "4111", "merchantCurrency": "AUD", "status": "AUTHORIZED", "totalAuthorizedAmount": 100.00, "totalCapturedAmount": 0.00, "totalDisbursedAmount": 0.00, "totalRefundedAmount": 0.00 }, "posTerminal": { "address": { "country": "AUS", "postcodeZip": "4000" }, "attended": "ATTENDED", "cardPresenceCapability": "CARD_PRESENT", "cardholderActivated": "MPOS_ACCEPTANCE_DEVICE", "inputCapability": "CONTACTLESS_CHIP", "lane": "teapost", "location": "MERCHANT_TERMINAL_ON_PREMISES", "mobile": { "cardInputDevice": "INTEGRATED_DONGLE" }, "panEntryMode": "CONTACTLESS", "pinEntryCapability": "PIN_SUPPORTED", "pinLengthCapability": 6, "serialNumber": "0123ABCD" }, "response": { "acquirerCode": "00", "acquirerMessage": "Approved", "gatewayCode": "APPROVED", "gatewayRecommendation": "NO_ACTION" }, "result": "SUCCESS", "sourceOfFunds": { "provided": { "card": { "brand": "AMEX", "emvRequest": { "5F2A": "840", "82": "0000", "84": "010101010101", "95": "0000000000", "9A": "161021", "9B": "0101", "9C": "00", "9F02": "000000001099", "9F03": "000000000000", "9F06": "010101010101", "9F07": "0101", "9F09": "0101", "9F10": "06011103A000000A0100000000000BB0ABAD", "9F1A": "840", "9F1E": "0123ABCD", "9F26": "D1F722D47FCA8273", "9F27": "40", "9F33": "E0B8C8", "9F34": "1E0300", "9F35": "12", "9F36": "0002", "9F37": "2A4E1690", "9F41": "0123", "9F53": "A", "9F6E": "0101" }, "emvResponse": { "72": "9F180408041215860E04DA9F5809030691D72E6F027DC6", "91": "B7D5309D4B3E6CDB3030" }, "expiry": { "month": "12", "year": "24" }, "fundingMethod": "CREDIT", "number": "345678xxxxx4564", "pin": { "encryptionState": "VALID", "keySerialNumber": "FFFF0000000004100499" }, "scheme": "AMEX", "sequenceNumber": "000", "storedOnFile": "NOT_STORED", "trackDataProvided": true } }, "type": "CARD" }, "timeOfLastUpdate": "2022-06-07T09:01:24.197Z", "timeOfRecord": "2022-06-07T09:01:24.058Z", "transaction": { "acquirer": { "batch": 20220607, "date": "0607", "id": "CYG_TESTACQ_S2I", "merchantId": "9808", "transactionId": "329712639801756" }, "amount": 100.00, "authenticationStatus": "AUTHENTICATION_NOT_IN_EFFECT", "authorizationCode": "112233", "currency": "AUD", "id": "806589378", "receipt": "215809027151", "source": "CARD_PRESENT", "stan": "27151", "terminal": "0002", "type": "AUTHORIZATION" }, "version": "67" } ``` ### Capture {#capture-3} | HTTP Method | URL | |-------------|------------------------------------------------------------------------------------------------------------| | PUT | https://{{host}}/api/rest/version/latest/merchant/{merchantId}/order/{orderid}/transaction/{transactionid} | ```json { "apiOperation": "CAPTURE", "transaction": { "amount": "100.00", "currency": "AUD" } } ``` ```json { "authorizationResponse": { "date": "0607", "posData": "0000004009300", "posEntryMode": "071", "processingCode": "003000", "responseCode": "00", "stan": "27151", "time": "090124", "transactionIdentifier": "329712639801756" }, "gatewayEntryPoint": "WEB_SERVICES_API", "merchant": "CYG_S2I_MER2", "order": { "amount": 100.00, "certainty": "FINAL", "chargeback": { "amount": 0, "currency": "AUD" }, "creationTime": "2022-06-07T09:01:24.028Z", "currency": "AUD", "id": "29796554", "lastUpdatedTime": "2022-06-07T09:01:28.770Z", "merchantAmount": 100.00, "merchantCategoryCode": "4111", "merchantCurrency": "AUD", "status": "CAPTURED", "totalAuthorizedAmount": 100.00, "totalCapturedAmount": 100.00, "totalDisbursedAmount": 0.00, "totalRefundedAmount": 0.00 }, "posTerminal": { "address": { "country": "AUS", "postcodeZip": "4000" }, "attended": "ATTENDED", "cardPresenceCapability": "CARD_PRESENT", "cardholderActivated": "MPOS_ACCEPTANCE_DEVICE", "inputCapability": "CONTACTLESS_CHIP", "lane": "teapost", "location": "MERCHANT_TERMINAL_ON_PREMISES", "mobile": { "cardInputDevice": "INTEGRATED_DONGLE" }, "panEntryMode": "CONTACTLESS", "pinEntryCapability": "PIN_SUPPORTED", "pinLengthCapability": 6, "serialNumber": "0123ABCD" }, "response": { "acquirerCode": "00", "acquirerMessage": "Approved", "gatewayCode": "APPROVED" }, "result": "SUCCESS", "sourceOfFunds": { "provided": { "card": { "brand": "AMEX", "expiry": { "month": "12", "year": "24" }, "fundingMethod": "CREDIT", "number": "345678xxxxx4564", "scheme": "AMEX", "sequenceNumber": "000", "storedOnFile": "NOT_STORED", "trackDataProvided": true } }, "type": "CARD" }, "timeOfLastUpdate": "2022-06-07T09:01:28.770Z", "timeOfRecord": "2022-06-07T09:01:28.741Z", "transaction": { "acquirer": { "batch": 20220607, "date": "0607", "id": "CYG_TESTACQ_S2I", "merchantId": "9808", "settlementDate": "2022-06-07", "timeZone": "+1000", "transactionId": "329712639801756" }, "amount": 100.00, "authorizationCode": "112233", "currency": "AUD", "id": "145809955", "receipt": "215809027151", "source": "CARD_PRESENT", "stan": "20852", "terminal": "0002", "type": "CAPTURE" }, "version": "67" } ``` ### Refund {#refund-3} | HTTP Method | URL | |-------------|------------------------------------------------------------------------------------------------------------| | PUT | https://{{host}}/api/rest/version/latest/merchant/{merchantId}/order/{orderid}/transaction/{transactionid} | ```json { "apiOperation": "REFUND", "transaction": { "amount": "100", "currency": "AUD" } } ``` ```json { "authorizationResponse": { "date": "0607", "posData": "0000004009300", "posEntryMode": "071", "processingCode": "203000", "responseCode": "00", "stan": "27151", "time": "090124", "transactionIdentifier": "329712639801756" }, "gatewayEntryPoint": "WEB_SERVICES_API", "merchant": "CYG_S2I_MER2", "order": { "amount": 100.00, "certainty": "FINAL", "chargeback": { "amount": 0, "currency": "AUD" }, "creationTime": "2022-06-07T09:01:24.028Z", "currency": "AUD", "id": "29796554", "lastUpdatedTime": "2022-06-07T09:01:55.041Z", "merchantAmount": 100.00, "merchantCategoryCode": "4111", "merchantCurrency": "AUD", "status": "REFUNDED", "totalAuthorizedAmount": 100.00, "totalCapturedAmount": 100.00, "totalDisbursedAmount": 0.00, "totalRefundedAmount": 100.00 }, "posTerminal": { "address": { "country": "AUS", "postcodeZip": "4000" }, "attended": "ATTENDED", "cardPresenceCapability": "CARD_PRESENT", "cardholderActivated": "MPOS_ACCEPTANCE_DEVICE", "inputCapability": "CONTACTLESS_CHIP", "lane": "teapost", "location": "MERCHANT_TERMINAL_ON_PREMISES", "mobile": { "cardInputDevice": "INTEGRATED_DONGLE" }, "panEntryMode": "CONTACTLESS", "pinEntryCapability": "PIN_SUPPORTED", "pinLengthCapability": 6, "serialNumber": "0123ABCD" }, "response": { "acquirerCode": "00", "acquirerMessage": "Approved", "gatewayCode": "APPROVED" }, "result": "SUCCESS", "sourceOfFunds": { "provided": { "card": { "brand": "AMEX", "expiry": { "month": "12", "year": "24" }, "fundingMethod": "CREDIT", "number": "345678xxxxx4564", "scheme": "AMEX", "sequenceNumber": "000", "storedOnFile": "NOT_STORED", "trackDataProvided": true } }, "type": "CARD" }, "timeOfLastUpdate": "2022-06-07T09:01:55.041Z", "timeOfRecord": "2022-06-07T09:01:55.020Z", "transaction": { "acquirer": { "batch": 20220607, "date": "0607", "id": "CYG_TESTACQ_S2I", "merchantId": "9808", "settlementDate": "2022-06-07", "timeZone": "+1000", "transactionId": "329712639801756" }, "amount": 100.00, "authorizationCode": "112233", "currency": "AUD", "id": "212144981", "receipt": "215809028221", "source": "CARD_PRESENT", "stan": "28221", "terminal": "0002", "type": "REFUND" }, "version": "67" } ``` ### Pay {#pay-3} | HTTP Method | URL | |-------------|------------------------------------------------------------------------------------------------------------| | PUT | https://{{host}}/api/rest/version/latest/merchant/{merchantId}/order/{orderid}/transaction/{transactionid} | ```json { "apiOperation": "PAY", "order": { "amount": "100.00", "currency": "AUD" }, "posTerminal": { "address": { "country": "AUS", "postcodeZip": "4000" }, "mobile": { "cardInputDevice": "BUILT_IN" }, "attended": "ATTENDED", "cardPresenceCapability": "CARD_PRESENT", "cardholderActivated": "MPOS_ACCEPTANCE_DEVICE", "inputCapability": "CONTACTLESS_CHIP", "lane": "teapost", "location": "MERCHANT_TERMINAL_ON_PREMISES", "panEntryMode": "CONTACTLESS", "pinLengthCapability": "6", "pinEntryCapability": "PIN_SUPPORTED" }, "sourceOfFunds": { "provided": { "card": { "emvRequest": { "5A": "345678901234564", "5F2A": "840", "5F24": "230603", "82": "0000", "84": "010101010101", "95": "0000000000", "9A": "161021", "9B": "0101", "9C": "00", "9F02": "000000001099", "9F03": "000000000000", "9F06": "010101010101", "9F07": "0101", "9F09": "0101", "9F10": "06011103A000000A0100000000000BB0ABAD", "9F1A": "840", "9F1E": "0123ABCD", "9F26": "D1F722D47FCA8273", "9F27": "40", "9F33": "E0B8C8", "9F34": "1E0300", "9F35": "12", "9F36": "0002", "9F37": "2A4E1690", "9F41": "0123", "9F53": "A", "9F6E": "0101" }, "expiry": { "month": "12", "year": "24" }, "sequenceNumber": "000", "number": "345678901234564", "track2": "345678901234564=241220116006711" } }, "type": "CARD" }, "transaction": { "source": "CARD_PRESENT" } } ``` ```json { "authorizationResponse": { "date": "0607", "posData": "0000000009300", "posEntryMode": "071", "processingCode": "003000", "responseCode": "00", "stan": "29301", "time": "090247", "transactionIdentifier": "300019768098940" }, "gatewayEntryPoint": "WEB_SERVICES_API", "merchant": "CYG_S2I_MER1", "order": { "amount": 100.00, "authenticationStatus": "AUTHENTICATION_NOT_IN_EFFECT", "chargeback": { "amount": 0, "currency": "AUD" }, "creationTime": "2022-06-07T09:02:47.309Z", "currency": "AUD", "id": "29796554", "lastUpdatedTime": "2022-06-07T09:02:47.510Z", "merchantAmount": 100.00, "merchantCategoryCode": "1234", "merchantCurrency": "AUD", "status": "CAPTURED", "totalAuthorizedAmount": 100.00, "totalCapturedAmount": 100.00, "totalDisbursedAmount": 0.00, "totalRefundedAmount": 0.00 }, "posTerminal": { "address": { "country": "AUS", "postcodeZip": "4000" }, "attended": "ATTENDED", "cardPresenceCapability": "CARD_PRESENT", "cardholderActivated": "MPOS_ACCEPTANCE_DEVICE", "inputCapability": "CONTACTLESS_CHIP", "lane": "teapost", "location": "MERCHANT_TERMINAL_ON_PREMISES", "mobile": { "cardInputDevice": "BUILT_IN" }, "panEntryMode": "CONTACTLESS", "pinEntryCapability": "PIN_SUPPORTED", "pinLengthCapability": 6 }, "response": { "acquirerCode": "00", "acquirerMessage": "Approved", "gatewayCode": "APPROVED", "gatewayRecommendation": "NO_ACTION" }, "result": "SUCCESS", "sourceOfFunds": { "provided": { "card": { "brand": "AMEX", "emvRequest": { "5F2A": "840", "82": "0000", "84": "010101010101", "95": "0000000000", "9A": "161021", "9B": "0101", "9C": "00", "9F02": "000000001099", "9F03": "000000000000", "9F06": "010101010101", "9F07": "0101", "9F09": "0101", "9F10": "06011103A000000A0100000000000BB0ABAD", "9F1A": "840", "9F1E": "0123ABCD", "9F26": "D1F722D47FCA8273", "9F27": "40", "9F33": "E0B8C8", "9F34": "1E0300", "9F35": "12", "9F36": "0002", "9F37": "2A4E1690", "9F41": "0123", "9F53": "A", "9F6E": "0101" }, "emvResponse": { "72": "9F180408041215860E04DA9F5809030691D72E6F027DC6", "91": "B7D5309D4B3E6CDB3030" }, "expiry": { "month": "12", "year": "24" }, "fundingMethod": "CREDIT", "number": "345678xxxxx4564", "scheme": "AMEX", "sequenceNumber": "000", "storedOnFile": "NOT_STORED", "trackDataProvided": true } }, "type": "CARD" }, "timeOfLastUpdate": "2022-06-07T09:02:47.510Z", "timeOfRecord": "2022-06-07T09:02:47.380Z", "transaction": { "acquirer": { "batch": 20220607, "date": "0607", "id": "CYG_TESTACQ_S2I", "merchantId": "9808", "settlementDate": "2022-06-07", "timeZone": "+1000", "transactionId": "300019768098940" }, "amount": 100.00, "authenticationStatus": "AUTHENTICATION_NOT_IN_EFFECT", "authorizationCode": "112233", "currency": "AUD", "id": "366371832", "receipt": "215809029301", "source": "CARD_PRESENT", "stan": "29301", "terminal": "0001", "type": "PAYMENT" }, "version": "67" } ``` ## Process an EMV Transaction {#process-an-emv-transaction} If card data is read from a card's chip (EMV cards only), * Request the terminal for these [EMV tags](https://developer.mastercard.com/mastercard-gateway/documentation/gateway-features/trans-enrich-data/cardholder-present-data/index.md#supported-emv-tags) (tags supported by the gateway). * Provide the returned tags in the `sourceOfFunds.provided.card.emvRequest` field as a JSON object in REST protocol, or as a collection of fields in NVP protocol (it is okay if your terminal does not supply all the supported EMV tags). Alert: EMV tag values must be formatted exactly as returned by the terminal --- binary values will be represented in hex format. * Provide the [mandatory fields](https://developer.mastercard.com/mastercard-gateway/documentation/gateway-features/trans-enrich-data/cardholder-present-data/index.md#mandatory-fields). * Provide the [optional fields](https://developer.mastercard.com/mastercard-gateway/documentation/gateway-features/trans-enrich-data/cardholder-present-data/index.md#optional-fields) if needed. **sourceOfFunds.provided.card.emvRequest** [\[REST\]](https://developer.mastercard.com/mastercard-gateway/documentation/api-reference/v100/rest/api-ops/index.md#transaction) [\[NVP\]](https://developer.mastercard.com/mastercard-gateway/documentation/api-reference/v100/nvp/api-ops/index.md#transaction) Some of the supported EMV tags correspond to core payment concepts, such as primary account number. These concepts also appear as API request fields, such as `sourceOfFunds.provided.card.number`. The API Reference documentation for these corresponding API request fields shows their linkage in the description. For example, the description for `sourceOfFunds.provided.card.number` contains the text "This field corresponds to EMV tag 5A". If you provide data as an EMV tag, then you need not provide the same as an API request field. The gateway populates the corresponding API request fields with the values provided in the EMV tags, where they exist, and uses these values across all internal processing, acquirer messaging, and transaction responses. For example, if you send `sourceOfFunds.provided.card.emvRequest.9F1C` with value 'Lane_03', then `posTerminal.lane` with value 'Lane_03' is sent to the acquirer and returned in the transaction response. Warning: You can provide EMV tags in place of API request fields. If required, you can choose to provide both EMV tags and the corresponding API request fields in the transaction request. See [Advanced Usage: Transaction Data in both EMV Tags and API Request Fields](https://developer.mastercard.com/mastercard-gateway/documentation/gateway-features/trans-enrich-data/cardholder-present-data/index.md#advanced-usage-transaction-data-in-both-emv-tags-and-api-request-fields). **This is an example EMV request and response in REST for a [Standalone Capture](https://developer.mastercard.com/mastercard-gateway/documentation/api-reference/v100/rest/api-ops/index.md#transaction) transaction where the authorization was performed offline at the terminal.** | HTTP Method | URL | |-------------|--------------------------------------------------------------------------------------------------------| | PUT | https://{{host}}/api/rest/version/72/merchant/{merchantId}/order/{orderid}/transaction/{transactionid} | ```json { "apiOperation": "CAPTURE", "transaction": { "currency": "EUR", "amount": "10.99", "source": "CARD_PRESENT" }, "sourceOfFunds": { "type": "CARD", "provided": { "card": { "number": "5457210089020012", "expiry": { "month": "1", "year": "39" }, "emvRequest": { "82": "0000", "95": "0000000000", "9F02": "000000001099", "9A": "161021", "5F2A": "840", "9F1A": "840", "9F10": "06011103A000000A0100000000000BB0ABAD", "9F34": "1E0300", "9F36": "0002", "9C": "00", "9F26": "D1F722D47FCA8273", "9F27": "40", "9F37": "2A4E1690", "9F33": "E0B8C8" } } } }, "posTerminal": { "inputCapability": "CONTACTLESS_CHIP", "panEntryMode": "CHIP", "pinEntryCapability": "PIN_SUPPORTED", "location": "MERCHANT_TERMINAL_ON_PREMISES", "lane": "Lane_03", "attended": "ATTENDED", "serialNumber": "123456789", "onlineReasonCode": "FORCED_BY_MERCHANT", "cardPresenceCapability": "CARD_PRESENT", "authorizationMethod": "OFFLINE", "address": { "country": "IRL", "city": "Dublin" } } } ``` ```json { "gatewayEntryPoint": "WEB_SERVICES_API", "merchant": "TESTSMOKE-RETAIL", "order": { "amount": 10.99, "creationTime": "2017-06-06T09:42:54.280Z", "currency": "EUR", "id": "sa-dfc1b030-4520-48ec-a7e0-889999d7e4ab", "status": "CAPTURED", "totalAuthorizedAmount": 10.99, "totalCapturedAmount": 10.99, "totalRefundedAmount": 0 }, "posTerminal": { "address": { "city": "Dublin", "country": "IRL" }, "attended": "ATTENDED", "authorizationMethod": "OFFLINE", "cardPresenceCapability": "CARD_PRESENT", "cardholderActivated": "NOT_CARDHOLDER_ACTIVATED", "inputCapability": "CONTACTLESS_CHIP", "lane": "Lane_03", "location": "MERCHANT_TERMINAL_ON_PREMISES", "onlineReasonCode": "FORCED_BY_MERCHANT", "panEntryMode": "CHIP", "pinEntryCapability": "PIN_SUPPORTED", "serialNumber": "123456789" }, "response": { "gatewayCode": "APPROVED" }, "result": "SUCCESS", "sourceOfFunds": { "provided": { "card": { "brand": "MASTERCARD", "emvRequest": { "82": "0000", "95": "0000000000", "5F2A": "840", "9A": "161021", "9C": "00", "9F02": "000000001099", "9F10": "06011103A000000A0100000000000BB0ABAD", "9F1A": "840", "9F26": "D1F722D47FCA8273", "9F27": "40", "9F33": "E0B8C8", "9F34": "1E0300", "9F36": "0002", "9F37": "2A4E1690" }, "emvResponse": { "4D3E": "456", "5A2F": "123" }, "expiry": { "month": "1", "year": "39" }, "fundingMethod": "DEBIT", "issuer": "CAPITAL ONE BANK (CANADA BRANCH)", "number": "545721xxxxxx0012", "scheme": "MASTERCARD" } }, "type": "CARD" }, "timeOfRecord": "2017-06-06T09:42:54.280Z", "transaction": { "acquirer": { "batch": 1, "id": "FOOBANK", "merchantId": "11223344" }, "amount": 10.99, "currency": "EUR", "frequency": "SINGLE", "id": "1", "receipt": "1706063974", "source": "CARD_PRESENT", "terminal": "0001", "type": "CAPTURE" }, "version": "43" } ``` ### Supported EMV tags {#supported-emv-tags} Here is a list of EMV tags supported by the gateway. If any of these are returned by the terminal, include it in `sourceOfFunds.provided.card.emvRequest` field. Alert: The gateway only accepts EMV tags on the **supported EMV tags** list --- requests that include any other tags are rejected.
| EMV Tag | Name | Mandatory | |---------|-----------------------------------------------------------------------------------------------------------|-----------| | 4F | Application identifier (AID) Name | - | | 56 | Track 1 | - | | 57 | Track 2 Equivalent Data | - | | 5A | Application Primary Account Number (PAN) | - | | 5F24 | Application Expiration Date | - | | 5F25 | Application Effective Date | - | | 5F28 | Issuer Country Code | - | | 5F2A | Transaction Currency Code | Yes | | 5F34 | Application Primary Account Number (PAN) Sequence Number | - | | 82 | Application Interchange Profile (AIP) | Yes | | 84 | Dedicated File Name | Yes | | 87 | Application Priority Indicator | - | | 95 | Terminal Verification Result (TVR) | Yes | | 9A | Transaction Date | Yes | | 9B | Transaction Status Information | - | | 9C | Transaction Type | Yes | | 9F02 | Amount Authorized | Yes | | 9F03 | Cashback Amount | - | | 9F06 | Application Identifier (AID) - Terminal | - | | 9F07 | Application Usage Control | - | | 9F08 | Application Version Number - ICC | - | | 9F09 | Application Version Number - Terminal | - | | 9F0D | Issuer Action Code - Default | - | | 9F0E | Issuer Action Code - Denial | - | | 9F0F | Issuer Action Code - Online | - | | 9F10 | Issuer Application Data (IAD) | Yes | | 9F1A | Terminal Country Code | Yes | | 9F1C | Terminal Identification | - | | 9F1E | Interface Device (IFD) Serial Number | - | | 9F21 | Transaction Time | - | | 9F26 | Application Cryptogram (AC) | Yes | | 9F27 | Cryptogram Information Data (CID) | Yes | | 9F33 | Terminal Capabilities | U.S only | | 9F34 | Cardholder Verification Method (CVM) Results | Yes | | 9F35 | Terminal Type | - | | 9F36 | Application Transaction Counter | Yes | | 9F37 | Unpredictable Number | Yes | | 9F39 | Point-of-Service (POS) Entry Mode | - | | 9F40 | Additional Terminal Capabilities | - | | 9F41 | Transaction Sequence Counter | - | | 9F49 | Dynamic Data Authentication Data Object List (DDOL) | - | | 9F53 | Transaction Category Code | - | | 9F5A | EMV (Kernel 3): Application Program Identifier (Program ID) EMV (Kernel 4): Membership Product Identifier | - | | 9F5B | EMV (Kernel 3): Issuer Script Results EMV (Kernel 2): DSDOL EMV (Kernel 4): Product Membership Number | - | | 9F66 | EMV (Kernel 2): PUNATC(Track2) EMV (Kernel 3): Terminal Transaction Qualifiers (TTQ) | - | | 9F6E | Form Factor Indicator | Yes | | 9F7C | Customer Exclusive Data (CED) | - | Warning: The minimum API version for PIN verified transactions is v77 and for Transit transactions is v66. ### Advanced Usage: Transaction Data in Both EMV Tags and API Request Fields {#advanced-usage-transaction-data-in-both-emv-tags-and-api-request-fields} If you provide both EMV tags and the corresponding API request fields in the transaction request, the gateway uses the value provided in the corresponding API request field. For example, if you send `sourceOfFunds.provided.card.emvRequest.9F1C` with value 'Lane_03' and `posTerminal.lane` with value 'Lane_04', then `posTerminal.lane` with value 'Lane_04' is sent to the acquirer and returned in the transaction response. This may be useful if you want to override the EMV tags and control values on a per-field basis. Note that such a usage is rare and hence must be considered only if your integration requires it. ### Supported EMV tags and the corresponding API request fields {#supported-emv-tags-and-the-corresponding-api-request-fields} This table lists EMV tags where the gateway populates the corresponding API request fields with the values provided in the EMV tags. | EMV Tag | EMV Tag Name | Corresponding API Request Field | |---------|------------------------------------------|----------------------------------------------------------------------------------| | 56 | Track 1 | sourceOfFunds.provided.card.track1 | | 57 | Track 2 Equivalent Data | sourceOfFunds.provided.card.track2 | | 5A | Application Primary Account Number (PAN) | sourceOfFunds.provided.card.number | | 5F24 | Application Expiration Date | sourceOfFunds.provided.card.expiry.year sourceOfFunds.provided.card.expiry.month | | 5F34 | PAN Sequence Number | sourceOfFunds.provided.card.sequenceNumber | | 9C | Cash Advance | order.cashAdvance | | 9F03 | Cashback Amount | order.cashbackAmount | | 9F1A | Terminal Country Code | posTerminal.address.country | | 9F1C | Terminal Identification | posTerminal.lane | | 9F1E | Interface Device Serial Number | posTerminal.serialNumber | | 9F33 | Terminal Capabilities | posTerminal.inputCapability posTerminal.pinEntryCapability | | 9F35 | Terminal Type | posTerminal.attended posTerminal.cardholderActivated | ### EMV Transaction Response {#emv-transaction-response} The gateway returns `sourceOfFunds.provided.card.emvResponse` field in the Retrieve Order and Retrieve Transaction response. This field contains data generated by the issuer, which the card/device can use for verification to complete or decline the transaction. It may also contain additional EMV tags from the issuer including tags echoed from the request. The table shows some EMV tags that may be returned in an online Authorization Response. | EMV Tag | Name | |---------|-----------------------------| | 8A | Authorization Response Code | | 89 | Authorization Code | | 91 | Issuer Authentication Data | | 71 | Issuer Script Template 1 | | 72 | Issuer Script Template 2 | The `sourceOfFunds.provided.card.emvRequest` field provided in the request is echoed back in the response where EMV tags identified as PCI sensitive are excluded. ### Voiding an EMV Transaction {#voiding-an-emv-transaction} Your acquirer may require additional EMV data elements to be included when voiding an EMV transaction. For example, EMV tag DF01 (Issuer Script Results) may be required. Contact your acquirer for specific requirements. ## Process a Magnetic Stripe Transaction {#process-a-magnetic-stripe-transaction} * Provide Track 1 data in `sourceOfFunds.provided.card.track1` or Track 2 data in `sourceOfFunds.provided.card.track2` fields. If both Track 1 and Track 2 are available from the terminal, then provide both in the transaction request. * Provide the [mandatory fields](https://developer.mastercard.com/mastercard-gateway/documentation/gateway-features/trans-enrich-data/cardholder-present-data/index.md#mandatory-fields). * Provide the [optional fields](https://developer.mastercard.com/mastercard-gateway/documentation/gateway-features/trans-enrich-data/cardholder-present-data/index.md#optional-fields) if needed. **sourceOfFunds.provided.card.track1** [\[REST\]](https://developer.mastercard.com/mastercard-gateway/documentation/api-reference/v100/rest/api-ops/index.md#transaction) [\[NVP\]](https://developer.mastercard.com/mastercard-gateway/documentation/api-reference/v100/nvp/api-ops/index.md#transaction) **sourceOfFunds.provided.card.track2** [\[REST\]](https://developer.mastercard.com/mastercard-gateway/documentation/api-reference/v100/rest/api-ops/index.md#transaction) [\[NVP\]](https://developer.mastercard.com/mastercard-gateway/documentation/api-reference/v100/nvp/api-ops/index.md#transaction) Warning: The card track data must contain the correct start and end sentinel characters and trailing longitudinal redundancy check (LRC) character. Card track 3 data is not supported. Here is an example of an online Authorization transaction using magnetic stripe data. | HTTP Method | URL | |-------------|--------------------------------------------------------------------------------------------------------| | PUT | https://{{host}}/api/rest/version/72/merchant/{merchantId}/order/{orderid}/transaction/{transactionid} | ```json { "apiOperation": "AUTHORIZE", "order": { "amount": 80, "currency": "AUD" }, "transaction": { "source": "CARD_PRESENT" }, "sourceOfFunds": { "type": "CARD", "provided": { "card": { "number": "5457210089020012", "sequenceNumber": "015", "expiry": { "year": "39", "month": "01" }, "track2": ";5123456789012346=17051019681143384001?", "track1": "%B5123456789012346^MR JOHN R SMITH ^17051019681143300001 840 ?;" } } }, "posTerminal": { "lane": "AdamLane", "panEntryMode": "SWIPE", "pinEntryCapability": "PIN_NOT_SUPPORTED", "attended": "UNATTENDED", "cardholderActivated": "SELF_SERVICE_TERMINAL", "inputCapability": "MAGNETIC_STRIPE", "location": "MERCHANT_TERMINAL_OFF_PREMISES" } } ``` ```json { "authorizationResponse": { "posData": "1605S0100130", "transactionIdentifier": "AmexTidTest" }, "gatewayEntryPoint": "WEB_SERVICES_API", "merchant": "TESTSMOKE-RETAIL", "order": { "amount": 80, "creationTime": "2017-05-31T07:49:46.351Z", "currency": "AUD", "id": "sa-e229682a-2163-47cf-b080-fb60dd148192", "status": "AUTHORIZED", "totalAuthorizedAmount": 80, "totalCapturedAmount": 0, "totalRefundedAmount": 0 }, "posTerminal": { "attended": "UNATTENDED", "cardholderActivated": "SELF_SERVICE_TERMINAL", "inputCapability": "MAGNETIC_STRIPE", "lane": "AdamLane", "location": "MERCHANT_TERMINAL_OFF_PREMISES", "panEntryMode": "SWIPE", "pinEntryCapability": "PIN_NOT_SUPPORTED" }, "response": { "acquirerCode": "00", "gatewayCode": "APPROVED" }, "result": "SUCCESS", "sourceOfFunds": { "provided": { "card": { "brand": "MASTERCARD", "expiry": { "month": "1", "year": "39" }, "fundingMethod": "DEBIT", "issuer": "CAPITAL ONE BANK (CANADA BRANCH)", "number": "545721xxxxxx0012", "scheme": "MASTERCARD", "sequenceNumber": "015", "trackDataProvided": true } }, "type": "CARD" }, "timeOfRecord": "2017-05-31T07:49:46.351Z", "transaction": { "acquirer": { "batch": 1, "id": "SYSTEST_ACQ1", "merchantId": "12345678" }, "amount": 80, "authorizationCode": "000001", "currency": "AUD", "frequency": "SINGLE", "id": "1", "receipt": "1705313", "source": "CARD_PRESENT", "terminal": "0006", "type": "AUTHORIZATION" }, "version": "43" } ``` ## Process a Keyed Transaction {#process-a-keyed-transaction} If the card number was manually been entered on your terminal's keypad, * Provide the keyed card number in `sourceOfFunds.provided.card.number` request field. * Provide the [mandatory fields](https://developer.mastercard.com/mastercard-gateway/documentation/gateway-features/trans-enrich-data/cardholder-present-data/index.md#mandatory-fields). * Provide the [optional fields](https://developer.mastercard.com/mastercard-gateway/documentation/gateway-features/trans-enrich-data/cardholder-present-data/index.md#optional-fields) if needed. **sourceOfFunds.provided.card.number** [\[REST\]](https://developer.mastercard.com/mastercard-gateway/documentation/api-reference/v100/rest/api-ops/index.md#transaction) [\[NVP\]](https://developer.mastercard.com/mastercard-gateway/documentation/api-reference/v100/nvp/api-ops/index.md#transaction) Here is an example of an online Authorization transaction using a manually keyed card number. | HTTP Method | URL | |-------------|--------------------------------------------------------------------------------------------------------| | PUT | https://{{host}}/api/rest/version/72/merchant/{merchantId}/order/{orderid}/transaction/{transactionid} | ```json { "posTerminal": { "serialNumber": "13130PP800781435", "cardholderActivated": "NOT_CARDHOLDER_ACTIVATED", "lane": "S2_Lane", "panEntryMode": "KEYED", "pinEntryCapability": "UNKNOWN", "attended": "ATTENDED", "inputCapability": "KEY_ENTRY", "location": "MERCHANT_TERMINAL_ON_PREMISES" }, "apiOperation": "AUTHORIZE", "sourceOfFunds": { "type": "CARD", "provided": { "card": { "number": "5457210089020012", "sequenceNumber": "000", "expiry": { "year": "39", "month": "01" } } } }, "order": { "amount": "100.00", "currency": "EUR" }, "transaction": { "source": "CARD_PRESENT" } } ``` ```json { "gatewayEntryPoint": "WEB_SERVICES_API", "merchant": "TESTSMOKE-RETAIL", "order": { "amount": 100, "creationTime": "2017-05-31T08:59:47.194Z", "currency": "EUR", "id": "sa-529e784a-e11d-474d-8012-c0790531bb0f", "status": "AUTHORIZED", "totalAuthorizedAmount": 100, "totalCapturedAmount": 0, "totalRefundedAmount": 0 }, "posTerminal": { "attended": "ATTENDED", "cardholderActivated": "NOT_CARDHOLDER_ACTIVATED", "inputCapability": "KEY_ENTRY", "lane": "S2_Lane", "location": "MERCHANT_TERMINAL_ON_PREMISES", "panEntryMode": "KEYED", "pinEntryCapability": "UNKNOWN", "serialNumber": "13130PP800781435" }, "response": { "gatewayCode": "APPROVED" }, "result": "SUCCESS", "sourceOfFunds": { "provided": { "card": { "brand": "MASTERCARD", "expiry": { "month": "1", "year": "39" }, "fundingMethod": "DEBIT", "issuer": "CAPITAL ONE BANK (CANADA BRANCH)", "number": "545721xxxxxx0012", "scheme": "MASTERCARD", "sequenceNumber": "000" } }, "type": "CARD" }, "timeOfRecord": "2017-05-31T08:59:47.194Z", "transaction": { "acquirer": { "batch": 1, "id": "FOOBANK", "merchantId": "11223344" }, "amount": 100, "authorizationCode": "471223", "currency": "EUR", "frequency": "SINGLE", "id": "1", "receipt": "170531475", "source": "CARD_PRESENT", "terminal": "0001", "type": "AUTHORIZATION" }, "version": "43" } ``` ## Integrating to use Online PIN {#integrating-to-use-online-pin} The online PIN entered by the cardholder is encrypted at source, within the PIN entry device. Mastercard Gateway supports ISO **format 0** with TDEA (Triple Data Encryption Algorithm) keys and \*\*format 4-pin blocks with AES (Advanced Encryption Standard) keys under DUKPT (Derived Unique Key Per Transaction) from API 45 onwards. * Provide the TDEA or AES encrypted PIN data from the terminal in the following fields: * `sourceOfFunds.provided.card.pin.payload` * `sourceOfFunds.provided.card.pin.keySerialNumber` * `posTerminal.pinLengthCapability` * `sourceOfFunds.provided.card.pin.encryptionState` * `sourceOfFunds.provided.card.pin.initializationVector` **Online PIN API Reference** [\[REST\]](https://developer.mastercard.com/mastercard-gateway/documentation/api-reference/v100/rest/api-ops/index.md#transaction) [\[NVP\]](https://developer.mastercard.com/mastercard-gateway/documentation/api-reference/v100/nvp/api-ops/index.md#transaction) * Provide the [mandatory fields](https://developer.mastercard.com/mastercard-gateway/documentation/gateway-features/trans-enrich-data/cardholder-present-data/index.md#mandatory-fields). * Provide the [optional fields](https://developer.mastercard.com/mastercard-gateway/documentation/gateway-features/trans-enrich-data/cardholder-present-data/index.md#optional-fields) if needed. ## Integrating to use mPOS {#integrating-to-use-mpos} The gateway supports accepting payments on mobile POS (mPOS) devices from API v56 onwards. To enable the functionality, provide the following in the Verify, Authorize, Capture, Pay, or Refund transaction: * `posTerminal.cardholderActivated`=MPOS_ACCEPTANCE_DEVICE * Provide the value of the card reader in the `posTerminal.mobile.cardInputDevice` * BUILT_IN: Off-the-shelf mobile phone or tablet with only a built-in contactless reader. In this case, `posTerminal.pinEntryCapability` must be set to SOFTWARE_ONLINE_PIN_ONLY else the gateway rejects the transaction. * INTEGRATED_DONGLE: Dedicated mobile terminal with an integrated card reader. In this case, `posTerminal.pinEntryCapability` must be set to PIN_SUPPORTED or OFFLINE_PIN_ONLY else the gateway rejects the transaction. * SEPARATE_DONGLE: Off-the-shelf device or dedicated mobile terminal, with a separate card reader. In this case, `posTerminal.pinEntryCapability` must be set to PIN_SUPPORTED or OFFLINE_PIN_ONLY else the gateway rejects the transaction. **mPOS API Reference** [\[REST\]](https://developer.mastercard.com/mastercard-gateway/documentation/api-reference/v100/rest/api-ops/index.md#transaction) [\[NVP\]](https://developer.mastercard.com/mastercard-gateway/documentation/api-reference/v100/nvp/api-ops/index.md#transaction) * Provide the [mandatory fields](https://developer.mastercard.com/mastercard-gateway/documentation/gateway-features/trans-enrich-data/cardholder-present-data/index.md#mandatory-fields). * Provide the [optional fields](https://developer.mastercard.com/mastercard-gateway/documentation/gateway-features/trans-enrich-data/cardholder-present-data/index.md#optional-fields) if needed. ### Transaction response {#transaction-response} The PIN authentication may fail if the payer enters an invalid PIN, exceeds the allowed PIN entry attempts, or skips PIN entry when PIN is required to complete the transaction. In these scenarios where the authorization fails due to a PIN authentication error, the gateway will return specific authorization response codes. You can reuse the same order ID on the next transaction. ## Test cardholder Present Integration {#test-cardholder-present-integration} You can test your integration using [test cards](https://developer.mastercard.com/mastercard-gateway/documentation/test-cards/index.md) specific to your acquirer.