Payment integration with Smartphone POS (iOS)

Version: 1.0

Introduction

This document specifies the structure and behavior of the SoftPOS iOS deep links.

The SoftPOS deep links allows external applications or web pages to seamlessly redirect users to the SoftPOS app and execute various operations. This simplifies the user experience by reducing manual data entry and ensuring data consistency.

Deep link structure

The SoftPOS app supports deep links using custom schemes with the following URI format:

				
					scheme://host/path?param=value

These values are:

scheme: Must be softpos. This parameter is defined at iOS application level.
host: Must be softpos. This parameter could accept different values in the future.
path: Request identifier, for example: transaction.

SoftPOS App deep link flow

SoftPOS app will handle the deep links executing the following steps:

Scheme Validation: If the scheme is incorrect the SoftPOS app will not be open. There is no additional scheme validation.
Path Validation: The operation will fail if the path parameter is incorrect.
Payload Extraction: If the payload parameter is not a valid JSON string the operation will fail.
Parameter Validation: If any required parameter is missing or invalid, the operation will fail and the SoftPOS app will stay on the main screen.
Execution: The requested operation will be executed
Completion: Upon completion the app will try to open the responseUrl if the parameter is provided as part of the deep link request. Otherwise will stay on the main application screen.

Deep Link requests

In the following sections you have the different types of Deep Link requests.

Transaction request: Sale and refund

This request allows Sale and Refund transactions. The type of transaction depends on the payload sent on the request.

Below is an example of a sale and its explanation:

				
					softpos://softpos/transaction?payload={"amount":200,"type":"sale","currency":"EUR","responseUrl":"testapp://response"}

transaction: Identifies the type of transaction: sale or refund.
payload: Encoded JSON object.

The field payload has the following structure:

				
					{
    "amount": <NUMBER>,
    "type": "<STRING>",
    "originalTranId": "<STRING OPTIONAL>", // only required in refunds
    "currency": "<STRING>",
    "responseUrl": "<STRING OPTIONAL>"
}

The field payload for Sales and Refunds has the following parameters:

Field	Format	Required/Optional	Description	Example
amount	Number	Required	Transaction amount. The last two digits are the decimals. For example, to indicate 2€, you must send the value 200.	200
type	Available values: – sale – refund	Required	Transaction type. Sale is “sale” and refund is “refund”.	sale
originalTranId	Alphanumeric	Optional*	Identifier of the original transaction to be refunded. * Only required for refunds.	446677
currency	Available values: – EUR	Required	ISO 4217 code for the currency of the transaction. Only the Euro “EUR” is available.	EUR
responseUrl	Alphanumeric	Optional	URL that will open when the transaction is complete. The SoftPOS application will automatically add a result query parameter containing the result of the operation. It must be a valid parameter managed by the application making the call.	testapp://response

Below are more examples of the JSON included in the Sale or Refund payload:

				
					{
    "amount": 200,
    "type": "sale",
    "currency": "EUR",
    "responseUrl": "testapp://response"
}

				
					{
    "amount": 200,
    "type": "refund",
    "originalTranId": "446655",
    "currency": "EUR",
    "responseUrl": "testapp://response"
}

Transaction response

Once completed, the SoftPOS application will open the field sent in responseUrl (if sent, as it is optional). The only requirement for the responseUrl parameter is that it is a valid parameter managed by the application making the call.

The SoftPOS application will automatically append a results query parameter, which is result. This parameter can contain one of the following two values, depending on the result of the operation:

result: This field will contain a JSON string with information about the result of the operation.
error: This field will contain a JSON string with information about the error in the operation.

Below is an example of the responseUrl in a failed transaction. This value will be encoded:

				
					testapp://response?result=%7B%22error%22:%7B%22description%22:%22The%20operation%20couldn%E2%80%99t%20be%20completed.%20(Softpos.SoftposReadError%20error%2010.)%22,%22softposReadError%22:%22readCancelled%22,%22errorDescription%22:%22The%20operation%20couldn%E2%80%99t%20be%20completed.%20(Softpos.SoftposReadError%20error%2010.)%22%7D%7D

				
					testapp://response?result={"error":{"description":"The operation couldn’t be completed. (Softpos.SoftposReadError error 10.)","softposReadError":"readCancelled","errorDescription":"The operation couldn’t be completed. (Softpos.SoftposReadError error 10.)"}}

JSON structure and parameters for result or error

The JSON structure for result or error is the following:

				
					{
  "result": {
    "refusalCode": "<STRING>",
    "transactionId": "<STRING>",
    "customMessage": {
      "...": "..."
    }
  }
}

				
					{
  "error": {
    "description": "<STRING>",
    "errorDescription": "<STRING OPTIONAL>",
    "softposReadError": "<STRING OPTIONAL>",
    "softposError": {
      "internalErrorCode": "<INT OPTIONAL>",
      "errorCode": "<INT OPTIONAL>",
      "errorSubCode": "<INT OPTIONAL>",
      "message": "<STRING OPTIONAL>"
    },
    "transactionResult": {
      "refusalCode": "<STRING>",
      "transactionId": "<STRING>",
      "customMessage": {
        "...": "..."
      }
    }
  }
}

The fields result or error contain the following parameters:

Field	Format	Required/Optional	Description	Example
refusalCode	Alphanumeric	Required	Operation code. “00” indicates that it was successful.	00
transactionId	Alphanumeric	Required	Transaction identificator.	446677
customMessage	Dictionary [string:string]	Required	String dictionary, with keys and values representing the information returned by the host.	N/A

Field	Format	Required/Optional	Description	Example
description	Alphanumeric	Required	Description of the error.	The operation couldn’t be completed. (Softpos.SoftposReadError error 10.)
errorDescription	Alphanumeric	Optional	Additional details about the error.	The operation couldn’t be completed. (Softpos.SoftposReadError error 10.)
softposReadError	Alphanumeric	Optional	String representing the error with the card reader.	readCancelled
softposError	JSON Object. Contains the fields: − internalErrorCode − errorCode − errorSubCode − message	Optional	Contains fields with information about the general error.	N/A
− internalErrorCode	Integer	Optional	Code indicating the internal system error number.	10
− errorCode	Integer	Optional	System error code.	10
− errorSubCode	Integer	Optional	System error subcode.	10
− message	Alphanumeric	Optional	Additional error message.	Read error
transactionResult	JSON Object. Contains the fields: − refusalCode − transactionId − customMessage	Optional*	Original response from the HOST if the transaction is rejected. * Received if the transaction is rejected by the HOST.	N/A
− refusalCode	Alphanumeric	Optional	Response code. Failed transactions have codes other than “00.”	105
− transactionId	Alphanumeric	Optional	Transaction identifier.	445577
− customMessage	Dictionary [string:string]	Optional	String dictionary, with keys and values representing the information returned by the host.	N/A

result or error JSON example

The following tabs show examples of the JSON included in the result or error field. Remember that these fields will be encoded and formatted:

				
					"result": {
    "refusalCode": "00",
    "transactionId": "449333",
    "customMessage": {
        "f39": "000",
        "isoStan": "000206",
        "transactionTime": "211812",
        "transactionDate": "250209"
    }
}

				
					"error": {
    "description": "Transaction Error: refusalCode:'105', transactionId:'', mti:'', customMessage:'[\"f39\": \"105\", \"isoStan\": \"000205\", \"transactionTime\": \"205432\", \"transactionDate\": \"250209\"]'",
    "errorDescription": "Transaction Error: refusalCode:'105', transactionId:'', mti:'', customMessage:'[\"f39\": \"105\", \"isoStan\": \"000205\", \"transactionTime\": \"205432\", \"transactionDate\": \"250209\"]'",
            "transactionResult": {
                "refusalCode": "105",
                "customMessage": {
                    "transactionDate": "250209",
                    "isoStan": "000205",
                    "transactionTime": "205432",
                    "f39": "105"
                }
            }
        }
    }
}

Deep Link sample code

On the home page of this section, you can download a sample code in Swift.

Payment integration with Smartphone POS (iOS)

Introduction

Deep link structure

SoftPOS App deep link flow

Deep Link requests

Transaction request: Sale and refund

Transaction response

JSON structure and parameters for result or error

result or error JSON example

Deep Link sample code

Products

Sales

Technical Support

Partners

SmartWiki, Powered by AI

Payment integration with Smartphone POS (iOS)

Introduction

Deep link structure

SoftPOS App deep link flow

Deep Link requests

Transaction request: Sale and refund

Transaction response

JSON structure and parameters for result or error

result or error JSON example

Deep Link sample code

Products

Sales

Technical Support

Partners

SmartWiki, Powered by AI

Consulta la documentación de las distintas secciones de integraciones:

Addon Payments

Cyberpac

POS integrated Payments

Addon Payments

Consult the documentation of the different integrations sections:​

Consult the documentation of the different integrations sections: