- POSresult: Once your POS receives the payment transaction response, use this to advise us of the results.

Transcription

1 To: Re: POS Providers Xpress-pay Mobile direct integration Thank you for your interest in Xpress-pay Mobile direct integration. You will be pleased to know the process is actually quite simple, requiring only three API calls to interact: - PostPOSbill: When the POS has a bill ready for the consumer to pay, use this API to post it to our database. Restaurants: In the event that the amount is updated, simply provide the new information in another post. We will recognize the duplication and update the bill. Mobile apps: Use this when the consumer has elected to Xpress-pay their bill and before navigating them to the Xpress-pay Mobile payment site. - POSpoll: The POS uses this method to poll Xpress-pay every few seconds to see if we have payments information pending. If we do, our response will include credit/debit card credentials needed for the POS to submit the payment. You should code to suspend polling if the POS has no open checks. - POSresult: Once your POS receives the payment transaction response, use this to advise us of the results. When your prototypes are prepared, we will assign a team member to assist with testing. This way, you will not need to become fully acquainted with the public-facing Xpress-pay Mobile components and use. After integrating, mobile apps simply display an Xpress-pay button. Restaurant systems can display a dynamic QR code on the printed check, or we can provide a static QR code for the establishment to include in the check folio. In the latter case, the patron simply enters the check number after scanning the QR code. Dynamic QR s provide additional convenience to patrons and add value to your product, while omitting them simplifies your initial effort. Our Technical Support Department remains available to assist you during your entire effort. For questions or support, please support@systemseast.com or call us at the number below. Thank you, James L. Buttino President

2 Developer Details for Direct Xpress-pay Mobile POS Integration The service page is located at both our development site ( and our production site ( You can use either as we have a demo merchant at each one. We recommend using only our live site as this will eliminate at least some of the otherwise redundant post-migration testing. Your involvement with integration will involve only three of the available methods. Since all API calls are via https and initiated from the merchant side, all transmissions are automatically encrypted and no special protocols or port-forwarding is required. Examples and parameter definitions follow this page. We have included safeguards and fault tolerance into the service as well: - For restaurants and hospitality, we understand that a person could scan their QR to retrieve their bill, and then add to it with a supplemental order. Consequently, when the patron actually submits their payment, we first verify that their bill payment amount (excluding tip) exactly matches the bill amount in our DB. If it does not match, they are immediately notified to start over. - When a payment is submitted, we write a record to a queue, where it awaits your poll. If you go offline and don t poll it, the record is marked as Expired in twenty-five seconds. The patron is then notified that the POS is not available. - When you poll us and we communicate payment information, we flag our queue record as Sent so we know you have it. Since it is possible that we may not receive a timely response from the POS, we will wait a maximum of twenty-five seconds prior to flagging the queue record as Sent/Expired. In such rare cases, the patron is then notified that the POS is not currently available. - Though we can adjust the timeout tolerance, you would do well to properly handle exceptions caused by an attempt to post a result to an expired queue record, though this would only occur if the time between passing payment credentials and receiving the pass/fail from you exceeds the timeout threshold. - Pending queue records are only transmitted once in response to a POSpoll. Consequently, when you receive payment information, you are encouraged to spawn your payment submission process separately and continue polling at your regular interval (asynchronous mode). Processing payments serially will elevate the likelihood of expirations. We look forward to working with you on the completion of this effort. Please contact us for additional information or clarification as needed.

3 Step one: Post your bill/check to our database Restaurants: When the POS prints a check destined for the table, post a copy of it in our database. If the check amount changes and the check is reprinted, repost the bill and we ll overwrite the old information with the new. When the patron initiates a transaction, we will retrieve the bill information and present the relevant components on their device. Mobile apps: When the patron elects to Xpress-pay their bill, post a copy of it in our database before redirecting them to Xpress-pay. Once they arrive, we will retrieve the bill information and present the relevant components on their device. - ibilltypepk: Required. The merchant ID we will assign to each establishment. For your integration project, use 1454 if you are using our development site and 2878 for the demo merchant at our live site. - Locator1: Required. The POS check number. - Locator2: Optional. The table ID. - Locator3: Optional. The text- or address of the person to be notified of payment. - SecurityCode: Required. The merchant s Xpress-pay API password (nydemo for the demo merchant). - Billamount: Required. The amount of the check. - Otheramount: Required (enter 0 if zero). The service charge we are to enforce. Response format: [Code],[ErrorSubcode],[ResponseText],0,[InternalBillID] Code 1: The check posted or updated successfully Code 9: Failure Sample responses: New bill, accepted: Existing bill, updated: Declined: 1,0,Posted,0, ,0,Updated,0, ,21,Configuration error,0

4 During the payment of any bill that permits a gratuity or mandatory service charge, the check amount (and separate mandatory service charge, if any) will be presented to the patron. The gratuity may be adjusted with +/- buttons or by entering an amount. The patron then continues within Xpress-pay Mobile to enter or select a card. The locator fields above are to be used as defined for restaurants, but for mobile apps, locators 2 through 5 may be used as you deem appropriate for any required information exchange. (continued)

5 Step two: Poll for payment information Once the patron has provided their payment information or selected a card stored in their Xpress-pay digital wallet, they tap the payment button. Xpress-pay Mobile then creates a queue record and awaits a result. It is expected that you will poll for payment information every few seconds. You can help us reduce traffic by suspending polling if you have no open checks. If the poll returns a 0, we have no payment activity queued. If we return a 1, the response will include the credit or debit card credentials, and we will mark the queued record as Sent so it will not be reported to you again. You should then spawn a separate function to submit the transaction through the existing merchant account and continue polling in case there are any more payments pending. Note: Upon receiving payment credentials, you will have twenty-five seconds to advise us of the result, otherwise we will assume there has been a communication error and advise the consumer of the failure. Consequently, we strongly recommend that you process payments asynchronously. - BillTypeID: The merchant ID we will assign. For your integration project, use 1454 if you are using our development site and 2878 if you are using the demo merchant at our live site. - Password: The merchant s API password (nydemo for the demo merchant on either site) Response format: [Code],[POScheckID],[QueueID],[CardName],[CardAddress],[CardCity],[CardState],[CardZip],[CardNumber], [ExpMonth],[ExpYear],[CVV],[BillPaymentAmount],[GratuityAmount] Code 0: No payments pending Code 1: Payment string follows (see example) Code 9: Error; either a bad BillTypeId or the merchant API password is incorrect Sample response: 1,55902,66,John Smith,12 Church St,Syracuse,NY,13202, ,8,2016,123,10.00,1.00 (continued)

6 Step three: Advise us of the results Once you have results from your payment submission, we need to know so we can advise the patron. - BillTypeID: The merchant ID we will assign. For your integration project, use 1454 if you are using our development site and 2878 if you are using the demo merchant at our live site. - QueueID: The queue record number provided to you in the POSpoll - Result: Approved or Declined in text form (no quotes) - ApprovalCode: Any code to associate the approval with your system - TransactionCode: The transaction ID assigned by the merchant provider - Password: The merchant s API password (nydemo for the demo merchant on either site) Response format: [Code],[ErrorSubcode],[ResultText] Code 1: Success Code [other]: Rejected. The reason is provided in the errorsubcode and the result text Sample responses: Accepted: 1,Result saved Declined 9,2,Queue record is already Approved Edge condition warning: It is possible that your transaction was successful but the queue record expired because your POSresult was submitted outside the twenty-five second response window. In this case, we will reject your POSresult, having already informed the patron that the POS did not respond, though their card would have actually been charged. Though this should never actually occur, you may wish to code accordingly, allowing the charge to be reversed.