Commerce SDK (CSDK) transaction flows: sale, void, refund, cancel and lookup

On this page

This is a condensed summary of the CSDK transaction flows in Elavon’s developer documentation. For every parameter and response field, see Elavon’s Commerce SDK documentation.

How do I run Start of Service (opening the application)?

Run this when your application opens. The paymentGatewayId you store in step 2 is used by every transaction that day.

1. Send openPaymentGateway command
2. Capture/Store the paymentGatewayId for use throughout the day
3. Send setDeviceConnectionConfiguration command with parameters of the peripherals that will be used
4. Send startCardReadersSearch command
5. Poll getCardReadersSearchStatus command until data->cardReadersSearch->completed = true
   • a) If successful in locating the reader, it will be listed in an array data->cardReadersSearch->cardReaders
   • b) If failure, send getDeviceConnectionConfiguration command to validate the configurations from step 3 were setup properly

How do I process a Card Present Sale (EMV/NFC/MSR)?

Use this when the cardholder inserts, taps or swipes their card.

1. Send startPaymentTransaction command: include paymentGatewayId from “Start of Service” step 2 & transactionType = SALE
2. Capture/Store the chanId for use throughout this transaction
3. Poll getPaymentTransactionStatus command: include paymentGatewayId & chanId
   • a) Continue polling until data->paymentGatewayCommand->completed = true
   • b) If the array requiredInformation appears in the response, parse the value and send a continuePaymentTransaction command with the requiste information (see “Process a Card Not Present Sale” step # for reference)
4. Parse through the response in step 3a for data->paymentGatewayCommand->paymentTransactionData->result
   • a) If APPROVED, capture/store the rest of the information within data->paymentGatewayCommand->paymentTransactionData and handle as needed within your payment solution (internal record keeping, receipt creating/printing, notifying the merchant and cardholder)
   • b) If DECLINED, notify the merchant and cardholder and prompt for another form of payment or different card (potentially start over at step 1)
   • c) If FAILED, parse the information within data->paymentGatewayCommand->paymentTransactionData->errors to determine the issue and handle accordingly (communication issues, card reader failures, card failure, user failure)

How do I process a Void of a Sale?

To void a sale, you need the originalTransId you stored when the sale was approved.

1. Send startPaymentTransaction command: include paymentGatewayId from “Start of Service” step 2, transactionType = VOID, & originalTransId (captured from “Process a Card Present Sale” step 4a)
2. Capture/Store the chanId for use throughout this transaction
3. Poll getPaymentTransactionStatus command: include paymentGatewayId & chanId
   • a) Continue polling until data->paymentGatewayCommand->completed = true
4. Parse through the response for data->paymentGatewayCommand->paymentTransactionData->result
   • a) If APPROVED, capture/store the rest of the information within data->paymentGatewayCommand->paymentTransactionData and handle as needed within your payment solution (internal record keeping, receipt creating/printing, notifying the merchant and cardholder)
   • b) If DECLINED, notify the merchant and cardholder (potentially start over at step 1 or look to completing a Stand-Alone Refund)
   • c) If FAILED, parse the information within data->paymentGatewayCommand->paymentTransactionData->errors to determine the issue and handle accordingly (communication issues, card reader failures, card failure, user failure)

How do I process a Stand-Alone Refund?

A stand-alone refund doesn’t need the original transaction ID.

1. Send startPaymentTransaction command: include paymentGatewayId from “Start of Service” step 2 & transactionType = STANDALONE_REFUND
2. Capture/Store the chanId for use throughout this transaction
3. Poll getPaymentTransactionStatus command: include paymentGatewayId & chanId
   • a) Continue polling until data->paymentGatewayCommand->completed = true
4. Parse through the response for data->paymentGatewayCommand->paymentTransactionData->result
   • a) If APPROVED, capture/store the rest of the information within data->paymentGatewayCommand->paymentTransactionData and handle as needed within your payment solution (internal record keeping, receipt creating/printing, notifying the merchant and cardholder)
   • b) If DECLINED, notify the merchant and cardholder (potentially start over at step 1)
   • c) If FAILED, parse the information within data->paymentGatewayCommand->paymentTransactionData->errors to determine the issue and handle accordingly (communication issues, card reader failures, card failure, user failure)

How do I process a Linked Refund?

A linked refund is tied to the original sale, so you include its originalTransId.

1. Send startPaymentTransaction command: include paymentGatewayId from “Start of Service” step 2, transactionType = LINKED_REFUND, & originalTransId (captured from “Process a Card Present Sale” step 4a)
2. Capture/Store the chanId for use throughout this transaction
3. Poll getPaymentTransactionStatus command: include paymentGatewayId & chanId
   • a) Continue polling until data->paymentGatewayCommand->completed = true
4. Parse through the response for data->paymentGatewayCommand->paymentTransactionData->result
   • a) If APPROVED, capture/store the rest of the information within data->paymentGatewayCommand->paymentTransactionData and handle as needed within your payment solution (internal record keeping, receipt creating/printing, notifying the merchant and cardholder)
   • b) If DECLINED, notify the merchant and cardholder (potentially start over at step 1 or look to completing a Stand-Alone Refund)
   • c) If FAILED, parse the information within data->paymentGatewayCommand->paymentTransactionData->errors to determine the issue and handle accordingly (communication issues, card reader failures, card failure, user failure)

How do I process a Card Not Present Sale?

Use this when the card details are keyed in rather than read by the device.

1. Send startPaymentTransaction command: include paymentGatewayId from “Start of Service” step 2, transactionType = SALE, & cardEntryTypes = ["MANUALLY_ENTERED"]
2. Capture/Store the chanId for use throughout this transaction
3. Send continuePaymentTransaction command: include paymentGatewayId, chanId, and cardPresent set to either true or false
4. Poll getPaymentTransactionStatus command: include paymentGatewayId & chanId
   • a) Continue polling until data->paymentGatewayCommand->completed = true
5. Parse through the response for data->paymentGatewayCommand->paymentTransactionData->result
   • a) If APPROVED, capture/store the rest of the information within data->paymentGatewayCommand->paymentTransactionData and handle as needed within your payment solution (internal record keeping, receipt creating/printing, notifying the merchant and cardholder)
   • b) If DECLINED, notify the merchant and cardholder (potentially start over at step 1 or look to completing a Stand-Alone Refund)
   • c) If FAILED, parse the information within data->paymentGatewayCommand->paymentTransactionData->errors to determine the issue and handle accordingly (communication issues, card reader failures, card failure, user failure)

How do I cancel an active transaction?

Use this while the cardholder is interacting with the PinPad/Peripheral/Device.

1. Send cancelPaymentTransaction command: include paymentGatewayId & chanId
2. Poll getPaymentTransactionStatus command: include paymentGatewayId & chanId
   • a) Continue polling until data->paymentGatewayCommand->completed = true
3. Parse through the response for data->paymentGatewayCommand->paymentTransactionData->result

   This will show “FAILED”, with data->paymentGatewayCommand->paymentTransactionData->errors = "ECLCommerceError ECLTransactionCanceled"

How do I look up a transaction?

1. Send searchPaymentTransaction command: include paymentGatewayId & any relevant data that would be associated with the specific transaction being searched
2. Parse through the response for data->paymentGatewayCommand->transactionSearchResults->transactions for any transaction objects for the specific transaction being searched