Documentation
Start typing to search…

Frequently asked questions

In this guide, you can find answers to frequently asked questions about SCI.

Getting Started

Q: What are the mandatory features required for SCI certification?

The following features are mandatory for SCI POS certification:

  • Pairing
  • Purchase
  • Action Framework
  • Transaction Recovery

Q: What credentials do I need to get started with SCI integration?

You will need the following credentials to begin:

  • Pairing API Key
  • Signing Secret Part A

These are provided by the mx51 team via a secure method. Once your POS is certified, a production (live) API Key will be issued and must be swapped in and tested before going live.

Q: Is there a sample POS I can use as a reference implementation?

Yes. mx51 provides a sample POS called Espresso POS, available at https://espressopos.mx51.io/. Use this as a reference for implementing the Action Framework, pairing UI, and transaction flows.

API Credentials, Authentication & Request Signing

Q: How do I generate the request signature headers?

SCI uses HMAC-SHA256 HTTP message signing. Each request must include the following headers:

More information is available on the API Credentials & Authentication page.

Q: I keep getting a 401 "no_valid_signatures_found" error. What am I doing wrong?

Common causes include:

  • The @authority header contains the schema (https://) - it must be the domain only.
  • Line feeds are present in the request body before hashing - strip all newlines from the POST body before computing the hash.
  • The signing secret used is incorrect - ensure you are using the correct Signing Secret Part A + Part B combination.
  • The @request-target path is wrong - e.g., using /api/v1/unpair instead of /v1/unpair.
  • Clock skew - ensure your server's clock is accurate (a difference of 6+ seconds can cause signature failures).

Pairing

Q: How does the pairing flow work?

Refer to the Pairing page for more details.

Important: The sci_api_base_url returned during pairing is dynamic and must be used for all subsequent transaction calls. Do not hardcode the sci_api_base_url - it can differ per pairing and may change.

Q: How do I check if the terminal is currently paired?

Call GET /v1/pairing-info. A 200 OK response indicates the pairing is active. A 401 response with code no_active_pairings_found means no active pairing exists.

Q: Can one POS support multiple paired terminals?

Yes. However, when a transaction is initiated, the POS must prompt the operator to select which paired terminal to use. Do not auto-assign a terminal without user input.

Q: How do I unpair a terminal?

Send a POST request to /v1/unpair. Note that even though the body is empty, you must still include the Content-Digest header computed from the empty JSON body {}:

Content-Digest: sha-256=RBNvo1WzZ4oRRq0W9+hknpT7T8If536DEMBg9hyq/4o=

Q: What happens if the pairing code is accepted on the POS but not confirmed on the terminal?

The pairing will not be active. The POS should validate the pairing by calling GET /v1/pairing-info after the operator enters the confirmation code on the terminal. Only show the pairing as active once a 200 OK is returned. Transactions cannot proceed until pairing is fully confirmed on both sides.

Transactions

Q: How does the transaction polling loop work?

After initiating a transaction (POST to create), poll GET /v1/transactions/{id}?min_version={next_version} to receive status updates. The transaction progresses through versions. Stop polling when status is FINALISED or AWAITING_POS.

Note: The min_version filter may not always be applied server-side once a transaction is FINALISED. Implement your own version and status checks rather than relying solely on API filtering.

Q: How do I know if a transaction was approved or declined?

Use the result_financial_status field to determine payment outcome - do not rely on parsing the message string. FINALISED only means the transaction flow ended, not that it was successful. result_financial_status indicates whether the merchant actually received payment.

Q: How do I trigger a signature transaction for testing?

Select Swipe > Credit > Next on the Gecko Bank terminal. This magic number triggers the signature flow.

Q: What is the POS-based signature flow and how do I implement it?

When verify_signature_on_terminal is set to false in the transaction request, the signature approval is handled on the POS rather than the terminal. The SCI API will return status: AWAITING_POS when the terminal is waiting for signature approval. The Action Framework will provide "Approve Signature" and "Decline Signature" buttons for the merchant to act on.

For Kiosk mode: only POS-based signature flow is supported. The POS should either auto-decline signature transactions or display a message instructing the customer to contact an operator.

Q: How should EFTPOS receipts be handled?

After each transaction, the SCI API returns both merchant_receipt and customer_receipt fields. The POS must consume these receipts and either:

  • Print them immediately (merchant copy and customer copy), or
  • Store them for later recall and printing.

Receipts must be available for declined transactions as well. The print_merchant_receipt and prompt_customer_receipt flags in the transaction request control whether the EFTPOS terminal itself prints receipts - set these to false if the POS is handling printing.

Action Framework

Q: What is the Action Framework?

The Action Framework is the mechanism by which the SCI API drives the POS transaction UI dynamically. Rather than the POS having a hardcoded UI, all transaction screens, buttons, inputs, and labels are defined in the pos_instructions.action_form field of the API response. The POS must render the UI based on this data for every transaction version - the UI must never be hardcoded.

Q: What elements can appear in the Action Framework?

The Action Framework supports four element types:

TypeDescription
buttonA clickable action. May have a submit_url (API call) or an action (e.g., TRANSACTION_COMPLETE, PRINT_MERCHANT_RECEIPT, RETRY_TRANSACTION).
inputA text input field for collecting operator data (e.g., email for a digital receipt).
textInformational text or labels.
imageA dynamically provided image (e.g., a signature).

All elements must be rendered dynamically based on the API response.

Q: How do I handle the "Submit to API" button?

When the action_form includes a Submit to API button:

  1. Collect values from all input fields in the form.
  2. Construct a JSON payload using each input's name property as the key.
  3. POST this payload to the submit_url specified in the button's properties.
  4. The API will return a new action_form - update the UI accordingly.

Q: How do I handle the "Call Test Function" button?

The Call Test Function button has action: "TEST_ACTION" and no submit_url. When clicked, the POS should call an internal function. For certification purposes, displaying the JSON payload for the "Submit to API" fields is acceptable.

Q: How should I handle emojis and special characters in Action Framework text?

The SCI API may include emojis (e.g., ✅, ❌) and other Unicode characters in text elements. The POS must render these without error. Do not rely on a known list of emojis - the API may use any Unicode character.

Q: How should I handle images in the Action Framework?

Image elements may contain any valid image (e.g., JPEG, PNG). The POS must dynamically render any image passed - do not assume a fixed image such as a logo. Ensure your image handling does not throw errors for unexpected image types or formats.

Transaction Recovery

Q: What is the Transaction Recovery (Override) flow?

Transaction Recovery handles outage scenarios where connection is lost mid-transaction. If the terminal completes the transaction and the POS doesn't receive the equivalent response, the POS must offer the operator an override dialog to manually confirm the transaction outcome.

The POS should implement a timeout: if no response is received within 1 minute of initiating a GET request, display the override dialog with options "Yes" (mark as paid) and "No" (keep as unpaid).

Q: What timeouts should I implement for the recovery flow?

ScenarioRecommended Timeout
Normal transaction polling (GET request, no response)1 minute, then show override dialog
Cancel transaction (no response after sending cancel)30 seconds, then show override dialog

For Kiosk mode: Set a timeout appropriate for your UX and display a message instructing the customer to contact an operator - do not allow the customer to manually close the transaction.

Q: What happens when the operator selects "Yes" in the override dialog?

When the operator selects "Yes", the POS should immediately mark the transaction as complete (paid). If the network is restored, a background GET request may be sent to reconcile - but the result of that GET must not reopen or affect the manually completed transaction.

Q: How do I test transaction override scenarios?

  • 1-minute timeout, terminal down: Initiate a transaction, then disconnect the terminal. After 1 minute of no response, the override dialog should appear automatically.
  • Cancel with terminal down: Click Cancel after the terminal has gone offline. The override dialog should appear after ~20 seconds.

Certification Process

Q: What is the certification process?

  1. Integration - Implement all mandatory features: Pairing, Purchase, Action Framework, Transaction Recovery.
  2. Internal Testing - Complete the SCI Test Run Sheet provided by mx51 and validate all applicable test cases.
  3. Integration Review - Share evidence (video recordings, test run sheet) with the mx51 team. A call may be scheduled to review the integration.
  4. QA Testing - mx51 QA performs a formal certification test run:
    • Browser/app-based POS: share app access or credentials.
    • Windows-based POS: mx51 creates a cloud VM and the POS team installs the build.
  5. Certification - Once all test cases pass, mx51 issues official certification and provides the production (live) API Key.
  6. Post-Certification - mx51's integration support and partnership team will follow up on next steps.
📥

Download the SCI Certification test suite

Q: What should I do before submitting for certification testing?

Before requesting certification testing, ensure:

  • All mandatory features are implemented (Pairing, Purchase, Action Framework, Transaction Recovery).
  • All mx51 references are removed from the POS UI - use SCI or Simple Cloud Integration instead.
  • Internal testing has been completed using the provided test run sheet.
  • The transaction UI is fully dynamic and compliant to the Action Framework.
  • EFTPOS receipts are consumed by the POS and are available for printing or stored.

Common Errors

Q: The API returns a 403 CloudFront error. What is happening?

The SCI API uses CloudFront with geographic whitelisting. If you receive a 403 with a message about blocked country access, your region has not been whitelisted. Contact the mx51 team to request that your country or region be added to the allowlist.

Q: The pairing shows as active on the POS but transactions fail. What should I check?

  • Confirm you are using the sci_api_base_url returned during the pairing response for transaction calls - not the pairing API URL.
  • Confirm the pairing was fully confirmed on the EFTPOS payment terminal (the merchant selected "Yes" on the terminal).
  • Call GET /v1/pairing-info to verify the pairing is still active.
  • Confirm that your POS and terminal are connected to the network with internet access.

Updated 12 days ago