Credit Card Processing Overview

At a Glance

There are 3 main steps to processing a credit card transaction:

  1. Start the transaction
  2. Poll the status of the transaction
  3. Finalize the transaction


Step 1: Start the transaction

The initial call is made to Polaris.ApplicationServices using the POST /api/.../creditcardpayments?task= route. This will create an entry in the ILSStoreOrders table and connect to the Innovative.Payments.Service to start a session on the device. Once this call is complete, the person paying by credit card should shift their focus to the credit card device and follow the instructions.

A pre-step is required when starting a refund transaction. The original payment data is required. In order to retrieve this payment data, use the "PatronsCredit" API POST /api/.../patrons/{patronid}/accounttransactions/credit?action=refundfrmpay route. This will return a flag indicating if credit card processing will be required. It will also contain the credit card data required to start the refund transaction.


Step 2: Poll the status of the transaction

The next call is made to Innovative.Payments.Service using the "PaymentsServiceUrl" value returned by the call made in Step 1. It may look like GET https://mylib.polarislibrary.com/Innovative.Payments.Service/api/payments/4375?guid=fdc8d7a3-ea1f-434b-a11a-d3d830a7&amount=0.01. The call is made while the person paying by credit card is interacting with the credit card device. Continue querying this endpoint until an error occurs or you receive a completed result.

A completed result should contain a "Result=0" value with a "TxnStatus" of "Finished" or "Failed". Save the result returned by this call as it will be required when finalizing the transaction in Step 3.


Step 3: Finalize the transaction

One of two calls is made to Polaris.ApplicationServices in order to finalize the credit card transaction. When finalizing a payment, call the PUT /api/.../patrons/{id}/accounttransactions/finesfees?action=pay&reload={true}&overpayment={true} route.
When finalizing a refund, call the POST /api/.../patrons/{id}/accounttransactions/credit?action=refundfrmpay route.

The "CreditCardPaymentData" value returned in Step 2, will be used when finalizing the transaction.


Other Notes

For Comprise development, if the Innovative.Payments.Service is in an "unknown" state, you may need to connect to the Comprise service directly to complete a transaction:

Finish: 

https://devst.comprisesmartpay.com/smartpayapi/websmartpay.dll?EndTransaction&CustomerID=82001&TerminalID=20012&UserName=Polaris&Password=xyz&Amount=0.01&TrackNo=0008200000200425&Result=Finish
Cancel:
https://devst.comprisesmartpay.com/smartpayapi/websmartpay.dll?EndTransaction&CustomerID=82001&TerminalID=20012&UserName=Polaris&Password=xyz&Amount=1.50&TrackNo=000820000020089&Result=Cancel


Example Refund

==> Caller attempts to refund a patron's account using "PatronsCredit" API route
POST /api/.../patrons/358247/accounttransactions/credit?action=refundfrmpay 
{
    "TxnAmount":"0.01",
    "PatronPaymentMethod":0,
    "FreeTextNote":"",
    "MainTxnIDs":[3707497]
}
<== Answer from server
The original payment was made using a credit card. Use the "CreditData" to build the data required to start a credit card refund transaction. 
{
    "CreditCardProcessRequired":true,
    "CreditData":{
        "PatronID":358247,
        "TxnAmount":0.01,
        "FreeTextNote":"",
        "PatronPaymentMethod":0,
        "MainTxnIDs":[3707497],
        "CreditCardPaymentData":{
            "TrackId":4375,
            "ILSStoreTransactionId":0,
            "Guid":null,
            "VendorId":5,
            "BaseAddress":null,
            "CustomerID":null,
            "TerminalID":null,
            "UserName":null,
            "Password":null,
            "Amount":0.01,
            "ProcessingFee":null,
            "PatronID":358247,
            "Language":null,
            "Result":0,
            "TrackNumber":null,
            "Error":null,
            "TxnStatus":null,
            "TroutId":null,
            "CCDigits":null,
            "CCType":null,
            "AuthCode":null,
            "Request":null,
            "Response":null,
            "PaymentsServiceUrl":null,
            "LastUnfinishedTrackId":0,
            "LastUnfinishedGuid":null
        }
    }
}
==> Caller starts a credit card transaction using "CreditCardPayment" API route. Use the data returned by the previous call to help build the data for this call
POST /api/.../creditcardpayments?task=9 
{
    "PatronID":358247,
    "TxnAmount":"0.01",
    "FreeTextNote":"Test refund",
    "PatronPaymentMethod":12,
    "MainTxnIDs":[3707497],
    "Charges":[],
    "CreditCardPaymentData":{
        "TrackId":4375,
        "ILSStoreTransactionId":0,
        "Guid":null,
        "VendorId":5,
        "BaseAddress":null,
        "CustomerID":null,
        "TerminalID":null,
        "UserName":null,
        "Password":null,
        "Amount":0.01,
        "ProcessingFee":null,
        "PatronID":358247,
        "Language":null,
        "Result":0,
        "TrackNumber":null,
        "Error":null,
        "TxnStatus":null,
        "TroutId":null,
        "CCDigits":null,
        "CCType":null,
        "AuthCode":null,
        "Request":null,
        "Response":null,
        "PaymentsServiceUrl":null,
        "LastUnfinishedTrackId":0,
        "LastUnfinishedGuid":null
    }
}
<== Answer from server
ILSStoreOrder has been created in the Polaris database. Awaiting user input at device. 
{
    "TrackId":4375,
    "ILSStoreTransactionId":0,
    "Guid":"fdc8d7a3-ea1f-434b-a11a-d3d830a7",
    "VendorId":0,
    "BaseAddress":null,
    "CustomerID":null,
    "TerminalID":null,
    "UserName":null,
    "Password":null,
    "Amount":null,
    "ProcessingFee":null,
    "PatronID":null,
    "Language":null,
    "Result":0,
    "TrackNumber":"0008200000200445",
    "Error":"OK",
    "TxnStatus":null,
    "TroutId":null,
    "CCDigits":null,
    "CCType":null,
    "AuthCode":null,
    "Request":"",
    "Response":"",
    "PaymentsServiceUrl":"https://mylib.polarislibrary.com/Innovative.Payments.Service/api/payments/4375?guid=fdc8d7a3-ea1f-434b-a11a-d3d830a7&amount=0.01",
    "LastUnfinishedTrackId":0,
    "LastUnfinishedGuid":null
}
==> Caller polls the status of the credit card transaction (cannot be done using PAS Swagger)
GET https://mylib.polarislibrary.com/Innovative.Payments.Service/api/payments/4375?guid=fdc8d7a3-ea1f-434b-a11a-d3d830a7&amount=0.01
<== Answer from server
Keep polling until the Result is 0 and TxnStatus is "Finished", "Failed" or an error occurs. 
{
    "TrackId":4375,
    "Guid":"fdc8d7a3-ea1f-434b-a11a-d3d830a7",
    "VendorId":0,
    "BaseAddress":null,
    "CustomerID":null,
    "TerminalID":null,
    "UserName":null,
    "Password":null,
    "Amount":0.01,
    "PatronID":null,
    "Language":null,
    "LastUnfinishedTrackId":0,
    "LastUnfinishedGuid":null,
    "Result":0,
    "TrackNumber":null,
    "Error":"OK",
    "TxnStatus":"Finished",
    "TroutId":"0704050437",
    "CCDigits":"2052",
    "CCType":"MAST",
    "AuthCode":null,
    "Request":"",
    "Response":"<Response><Status>Credit Success</Status><TroutID>0704050437</TroutID><Error>OK</Error><CCDigits>2052</CCDigits><CCType>MAST</CCType></Response>"
}
==> Caller finalizes the credit card transaction using "PatronsCredit" API route
POST /api/.../patrons/358247/accounttransactions/credit?action=refundfrmpay 
{
    "PatronID":358247,
    "TxnAmount":"0.01",
    "FreeTextNote":"Test refund",
    "PatronPaymentMethod":12,
    "MainTxnIDs":[3707497],
    "Charges":[],
    "CreditCardPaymentData":{
        "TrackId":4375,
        "Guid":"fdc8d7a3-ea1f-434b-a11a-d3d830a7",
        "VendorId":0,
        "BaseAddress":null,
        "CustomerID":null,
        "TerminalID":null,
        "UserName":null,
        "Password":null,
        "Amount":0.01,
        "PatronID":null,
        "Language":null,
        "LastUnfinishedTrackId":0,
        "LastUnfinishedGuid":null,
        "Result":0,
        "TrackNumber":null,
        "Error":"OK",
        "TxnStatus":"Finished",
        "TroutId":"0704050437",
        "CCDigits":"2052",
        "CCType":"MAST",
        "AuthCode":null,
        "Request":"",
        "Response":"<Response><Status>Credit Success</Status><TroutID>0704050437</TroutID><Error>OK</Error><CCDigits>2052</CCDigits><CCType>MAST</CCType></Response>",
        "ProcessingFee":0,
        "ILSStoreTransactionId":0,
        "amount":0.01
    }
}
<== Answer from server
Transaction has been recorded in the Polaris database. You may now refresh UI, etc. 
{
    "CreditCardProcessRequired":false,
    "CreditData":{
        "PatronID":358247,
        "TxnAmount":0.01,
        "FreeTextNote":"Test refund",
        "PatronPaymentMethod":12,
        "MainTxnIDs":[3707498],
        "CreditCardPaymentData":null
    }
}