Integración de pago con Smartphone TPV (iOS)

  • Versión: 1.0

Introducción

Este documento especifica la estructura y el comportamiento de los deep links de SoftPOS iOS.

Los deep links de SoftPOS permiten que aplicaciones externas o páginas web redirijan a los usuarios de forma fluida a la aplicación SoftPOS y ejecuten diversas operaciones. Esto simplifica la experiencia de usuario al reducir la introducción manual de datos y garantizar la consistencia de la información.

Estructura de los Deep Link

La aplicación SoftPOS admite deep links mediante esquemas personalizados con el siguiente formato de URI:

				
					scheme://host/path?param=value
Siendo los valores:
  • scheme: Debe ser softpos. Este parámetro se define a nivel de la aplicación iOS.
  • host: Debe ser softpos. Este parámetro podría aceptar valores diferentes en el futuro.
  • path: Identificador de la petición, por ejemplo: transaction.

Flujo de Deep Link en la app SoftPOS

La aplicación SoftPOS gestionará los deep links ejecutando los siguientes pasos:
  1. Validación del esquema: Si el esquema es incorrecto, la aplicación SoftPOS no se abrirá. No existe una validación adicional del esquema.
  2. Validación del path: La operación fallará si el parámetro path es incorrecto.
  3. Extracción del payload: Si el parámetro payload no es una cadena JSON válida, la operación fallará.
  4. Validación de parámetros: Si falta algún parámetro obligatorio o es inválido, la operación fallará y la aplicación SoftPOS permanecerá en la pantalla principal.
  5. Ejecución: Se ejecutará la operación solicitada.
  6. Finalización: Al finalizar, la aplicación intentará abrir la responseUrl si este parámetro se ha proporcionado como parte de la solicitud del deep link. En caso contrario, permanecerá en la pantalla principal de la aplicación.

Peticiones de Deep Link

En las siguientes secciones tienes los distintos tipos de peticiones de Deep Link.

Petición de transacción: Venta y devolución

Esta petición admite transacciones de Venta y Devolución, dependiendo de la payload/parámetros enviados.

A continuación tienes un ejemplo de venta y la explicación del mismo: 

				
					softpos://softpos/transaction?payload={"amount":200,"type":"sale","currency":"EUR","responseUrl":"testapp://response"}
  • transaction: Identificador del tipo de petición.
  • payload: Objeto JSON codificado.

El campo payload tiene la siguiente estructura:

				
					{
    "amount": <NUMBER>,
    "type": "<STRING>",
    "originalTranId": "<STRING OPTIONAL>", // sólo requerido en devoluciones
    "currency": "<STRING>",
    "responseUrl": "<STRING OPTIONAL>"
}

El campo payload para ventas o devoluciones contiene los siguientes parámetros:

ParámetroFormatoRequerido/OpcionalDescripciónEjemplo
amountNuméricoRequeridoImporte de la transacción. Los dos últimos dígitos son los decimales. Por ejemplo, para indicar 2€ hay que enviar el valor 200. 200
typeValores disponibles:
– sale
– refund		RequeridoTipo de transacción. Venta es «sale» y devolución «refund». sale
originalTranIdAlfanuméricoOpcional* Identificador de la transacción original que se quiere devolver.

* Sólo requerido en devoluciones		446677
currencyValor disponible:
– EUR		RequeridoCódigo ISO 4217 de la divisa de la operación. Sólo está disponible el Euro «EUR».EUR
responseUrlAlfanumérico OpcionalURL que se abrirá cuando se complete la transacción. La aplicación SoftPOS añadirá automáticamente un parámetro de consulta de resultados que contendrá el resultado de la operación.

Tiene que ser un parámetro válido gestionado por la aplicación que realiza la llamada. 		testapp://response

A continuación tienes más ejemplos del JSON incluido en el payload de venta o devolución:

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

Respuesta de la transacción

Una vez finalizado, la aplicación SoftPOS abrirá el campo enviado en responseUrl (en caso de que se haya enviado, ya que es opcional). El único requisito para el parámetro responseUrl es que sea un parámetro válido gestionado por la aplicación que realiza la llamada.

La aplicación SoftPOS añadirá automáticamente un parámetro de consulta de resultados, este parámetro es result. Este parámetro puede contener uno de los dos siguientes valores, dependiendo del resultado de la operación:

  • result: Este campo contendrá un JSON en formato cadena con la información sobre el resultado de la operación.
  • error: Este campo contendrá un JSON en formato cadena con la información sobre el error de la operación.

A continuación tienes un ejemplo del responseUrl en una transacción fallida. Este valor vendrá codificado:

				
					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.)"}}

Estructura y parámetros JSON de result o error

La estructura del JSON de result o error es la siguiente:

				
					{
  "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": {
        "...": "..."
      }
    }
  }
}

Los campos result o error contienen los siguientes parámetros:

ParámetroFormatoRequerido/OpcionalDescripciónEjemplo
refusalCodeAlfanuméricoRequeridoCódigo de la operación. El «00» indica que es exitosa.00
transactionIdAlfanuméricoRequeridoNúmero de transacción446677
customMessageDiccionario [cadena: cadena]RequeridoDiccionario de cadenas, con claves y valores que representan la información devuelta por el host. N/A
ParámetroFormatoRequerido/OpcionalDescripciónEjemplo
descriptionAlfanuméricoRequeridoDescripción del error.The operation couldn’t be completed. (Softpos.SoftposReadError error 10.)
errorDescriptionAlfanuméricoOpcionalDetalles adicionales sobre el error.The operation couldn’t be completed. (Softpos.SoftposReadError error 10.)
softposReadErrorAlfanuméricoOpcionalCadena que representa el error con el lector de tarjeta.readCancelled
softposErrorObjeto JSON. Contiene los campos:
− internalErrorCode
− errorCode
− errorSubCode
− message		OpcionalContiene campos con información sobre el error general.N/A
− internalErrorCodeNumérico enteroOpcional Código que indica el número de error en el sistema interno. 10
− errorCodeNumérico enteroOpcional Código de error del sistema. 10
− errorSubCodeNumérico enteroOpcional Sub código de error del sistema.10
− messageAlfanuméricoOpcional Mensaje adicional de error. Read error
transactionResultObjeto JSON. Contiene los campos:
− refusalCode
− transactionId
− customMessage		Opcional* Respuesta original del HOST si la transacción es rechazada.

* Recibido si la transacción es rechazada por el HOST.		N/A
− refusalCodeAlfanuméricoOpcionalCódigo de respuesta. Las transacciones fallidas tienen códigos distintos a «00». 105
− transactionIdAlfanuméricoOpcionalIdentificador de transacción.445577
− customMessageDiccionario [cadena: cadena]OpcionalDiccionario de cadenas, con claves y valores que representan la información devuelta por el host.N/A

Ejemplos del JSON de result o error

En las siguientes pestañas tienes un ejemplo de los JSON que se incluyen en el campo result o error. Recuerda que estos campos vendrán codificados y formateados: 

				
					"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"
                }
            }
        }
    }
}

Código de ejemplo Deep Link

En la página de inicio de esta sección puedes descargar un código de ejemplo en Swift. 

Comparte este documento
Tabla de Contenidos

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

Comienza a integrar

undraw_add_to_cart_re_wrdo 1 (1) (1)

Plugins para CMS

Complementa la integración

SDKs

Métodos de pago

Herramientas

Addon Payments

Consulta la documentación de Addon Payments. Aquí tienes las distintas secciones:

Integraciones

Consultas frecuentes

Portal Backoffice

Cyberpac

Consulta la documentación de Cyberpac. Aquí tienes las distintas secciones:

Canales

Módulos de integración

Integraciones a medida

Pagos integrados en TPV

Crea una solución que te ayudará a automatizar procesos. Incluso, podrás agregar procesos de pago en terminales físicos.

Pago integrado con TPV Android

Pago integrado con Smartphone TPV

Fichas Técnicas TPVs

Addon Payments

Comercia Global Payments has several integration options so you can choose the most efficient one for you.

Integrations

Frequently Asked Questions

BackOffice Portal

Consult the documentation of the different integrations sections:​

Start integration

undraw_add_to_cart_re_wrdo 1 (1) (1)

CMS Plugins

Complement your integration

SDKs

Payment Methods

Tools