El siguiente proyecto constituye una SDK en python, que simplifica la ejecución de llamadas al servicio Ecommerce de Sipay.
Con el siguiente ejemplo podrás, en pocos pasos, instalar la SDK y efectuar una venta desde una terminal.
$ git clone https://github.com/sipay/python-sdk
$ pip install ./python-sdk
$ cd python-sdk
$ python
>>> from sipay import Ecommerce
>>> ecommerce = Ecommerce('etc/config.ini') # Establecer la configuración como se indica en la sección 4.Configuración
>>> from sipay.paymethod.card import Card
>>> from sipay.amount import Amount
>>> amount = Amount(100, 'EUR') # 1.00 EUR
>>> card = Card('4242424242424242', 2050, 1)
>>> auth = ecommerce.authorization(card, amount)
>>> if auth.code == 0:
>>> print("Autorización aceptada, el pago ha sido completado!")
- Versión de python 3.5 o superior.
$ git clone https://github.com/sipay/python-sdk
$ pip install ./python-sdk
Una vez que se ha instalado la SDK, se deben actualizar los parámetros de configuración asociados a:
- Sistema de trazas.
- Credenciales de acceso (Se gestionan con el departamento de integraciones de Sipay).
- Entorno y versión de la API.
- Tiempo máximo de espera de respuestas (Timeout).
Un ejemplo de configuraciones se muestra a continuación:
# **************************************************************
# LOGGER
# ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
# Configuración asociada al sistema de trazas.
#
# file: Nombre y ruta del archivo de logs. (Nota: Aconsejable usar rutas absolutas
# para que se pueda ejecutar el módulo desde diferentes localizaciones).
# level: Nivel mínimo de trazas [debug, info, warning, error, critical]
# max_file_size: Tamaño máximo del fichero de trazas [bytes]
# backup_file_rotation: Número de ficheros de backup
# ------------------------------------------------------------//
[logger]
file=logs/info.log
level=warning
max_file_size = 51200000
backup_file_rotation = 5
# **************************************************************
# CREDENTIALS
# ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
# Credenciales para obtener acceso al recurso.
#
# key: Key del cliente
# secret: Secret del cliente
# resource: Recurso al que se quiere acceder
# ------------------------------------------------------------//
[credentials]
key=api-key
secret=api-secret
resource=resource
# **************************************************************
# API
# ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
# Configuración de la API.
#
# environment: Entorno al que se deben enviar las peticiones ['sandbox', 'staging', 'live']
# version: Versión de la api a usar actualmente solo existe v1
# mode: Modo de cifrado de la firma, [sha256, sha512]
# ------------------------------------------------------------//
[api]
environment=sandbox
version=v1
mode=sha256
# **************************************************************
# TIMEOUT
# ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
# Configuración de los tiempos de timeout.
#
# connection: Timeout de connexión en segundos
# process: Timeout de procesamiento en segundos
# ------------------------------------------------------------//
[timeout]
connection=3
process=27
A través de peticiones a Sipay mediante Ecommerce, se pueden realizar operativas de:
- Autorizaciones (sección 5.2.1).
- Cancelaciones (sección 5.2.2).
- Devoluciones (sección 5.2.3).
- Búsquedas de operaciones o querys (sección 5.2.4).
- Tokenización* de tarjetas (sección 5.2.5).
- Búsqueda de tarjetas tokenizadas (sección 5.2.6).
- Dar de baja una tarjeta tokenizada (sección 5.2.7).
- Preautorización (sección 5.2.8).
- Confirmación de una preautorización (sección 5.2.9).
- Desbloqueo de una preautorización (sección 5.2.10).
* Tokenización: Es un proceso por el cual el PAN (Primary Account Number – Número Primario de Cuenta) de la tarjeta se sustituye por un valor llamado token. Esta funcionalidad permite que Sipay guarde los datos de la tarjeta del cliente, para agilizar el proceso de pagos y evitar que se deba introducir, cada vez, los datos de tarjeta, en pagos repetitivos. Sipay realiza el almacenamieno de los datos de forma segura, cumpliendo con las normativas PCI.
Para llevar a cabo de forma correcta las operativas Ecommerce, se requiere el dominio de los objetos Amount
, Card
, StoredCard
y FastPay
, los cuales identifican el importe y el método de pago a utilizar.
Este objeto representa una cantidad monetaria, por tanto esta cantidad debe ser mayor que cero (0). Para instanciar un objeto de este tipo se necesita una cantidad (amount) y una moneda (currency) en formato ISO4217 (https://en.wikipedia.org/wiki/ISO_4217). La cantidad se puede especificar de dos formas:
- Con un
string
con la cantidad estandarizada y con el caracter punto (.
) como separador de decimales , o - Con un
int
que represente la cantidad en la unidad básica e indivisible de la moneda (por ejemplo de la moneda Euro sería el céntimo).
amount
: [obligatorio] Es la cantidad de dinero a procesar. Se puede representar con unstring
o unint
. Supongamos que queremos procesar 1.56 €, la cantidad (1.56) como unstring
sería'1.56'
; como unint
sería156
.currency
: [obligatorio] Es unstring
que representa el código de la moneda (ISO4217).
amount
:int
que representa la cantidad de procesamiento. Será este tipo de dato, independientemente de si se ha instanciado con unstring
previamente.currency
:string
que representa el código de la moneda (ISO4217).
from sipay.amount import Amount
# Con string
amount = Amount('1.56', 'EUR')
print(amount)
# Imprime 1.56EUR
print(amount.amount)
# Imprime 156
print(amount.currency)
# Imprime EUR
# Con unidad indivisible
amount = Amount(156, 'EUR')
print(amount)
# Imprime 1.56EUR
print(amount.amount)
# Imprime 156
print(amount.currency)
# Imprime EUR
Nota: En el caso de iniciarlo con el string
es imprescindible que tenga el número de decimales que indica el estándar ISO4217.
Este objeto representa una tarjeta que se puede utilizar en las diferentes operativas de Ecommerce. Para obtener una instancia de Card
, los parámetros se indican a continuación.
card_number
: [obligatorio] Es unstring
con longitud entre 14 y 19 dígitos. Representa el número de la tarjeta.year
: [obligatorio] Es unint
de 4 dígitos que indica el año de caducidad de la tarjeta.month
: [obligatorio] Es unint
de 2 dígitos con valores entre 1 y 12 que correspondiente al mes de caducidad de la tarjeta.
card_number
: Es el número de la tarjeta en una instancia deCard
. Es unstring
con longitud entre 14 y 19 dígitos.year
: Es al año de caducidad de la tarjeta en una instancia deCard
. Es unint
de 4 dígitos.month
: Es el mes de caducidad de la tarjeta en una instancia deCard
. Es unint
de 2 dígitos entre 1 y 12.
set_expiration_date(year, month)
: Permite asignar una fecha de caducidad sobre una instancia deCard
. Los parámetrosyear
ymonth
son obligatorios.is_expired()
: Permite evaluar si una instancia deCard
tiene una fecha de caducidad válida. RetornaTrue
si la tarjeta está expirada.
from sipay.paymethod.card import Card
card = Card('4242424242424242', 2050, 2)
print(card.card_number)
print(card.year)
print(card.month)
card.card_number='123451234512345'
print(card.card_number)
card.set_expiration_date(2021, 12)
print(card.year)
print(card.month)
result = card.is_expired()
print(result)
Este objeto representa una tarjeta almacenada en Sipay que puede utilizarse en operativas Ecommerce. Para obtener una instancia de StoredCard
se requieren los siguiente parámetros.
token
: [obligatorio] Es unstring
de longitud entre 6 y 128 caracteres de tipo alfanuméricos y guiones.
token
:string
de longitud entre 6 y 128 caracteres.
from sipay.paymethod.storedcard import StoredCard
card = StoredCard('token-card')
print(card.token)
# Imprime token-card
card.token = 'new-token-card'
print(card.token)
# Imprime new-token-card
Este objeto representa una tarjeta obtenida mediante el método de pago FastPay. Se utiliza en los consecutivos pasos de la operativas de pago de este método.
token
: [obligatorio] Es unstring
de longitud 32 con caracteres de tipo hexadecimal.
token
:string
de longitud 32 caracteres de tipo hexadecimal.
from sipay.paymethod.fastpay import FastPay
fp = FastPay('token-fast-pay')
print(fp.token)
fp = FastPay('new-token-fast-pay')
print(fp.token)
Las operativas de Ecommerce forman parte de los métodos definidos en la clase Ecommerce
. Para instanciar un objeto de este tipo se requiere el archivo de configuración.
config_file
[obligatorio] Es unstring
con la ruta del archivo de configuraciones.
from sipay import Ecommerce
ecommerce = Ecommerce('etc/config.ini')
Los siguientes atributos se asignan en el archivo de configuraciones. Sin embargo, son accesibles en instancias de Ecommerce
. Se sugiere que sean utilizados en modo de consulta.
key
: corresponde al key de las credenciales.secret
: corresponde al secret de las credenciales.resource
: corresponde al resource de las credenciales.environment
: corresponde al entorno al cual se está apuntando.mode
: corresponde el modo de cifrado de las peticiones.version
: corresponde a la versión de la API a la cual se apunta.conn_timeout
: Corresponde al tiempo de espera máximo en establecer una conexión.process_timeout
: Corresponde al tiempo de espera máximo en esperar la respuesta de un proceso.
authorization(parameters)
: Permite hacer peticiones de autorización haciendo uso de los diferentes métodos de pago (ver sección 5.2.1).cancellation(parameters)
: Permite enviar peticiones de cancelaciones (ver sección 5.2.2).refund(parameters)
: Permite hacer devoluciones (ver sección 5.2.3).query(parameters)
: Permite hacer peticiones de búsqueda de operaciones (ver sección 5.2.4).register(parameters)
: Permite tokenizar una tarjeta (ver sección 5.2.5).card(parameters)
: Se utiliza para buscar una tarjeta que fue tokenizada (ver sección 5.2.6).unregister(parameters)
: Se utiliza para dar de baja una tarjeta tokenizada (ver sección 5.2.7).
5.2.1 authorization(paymethod, amount, order='order', reconciliation='reconciliation', custom_01='custom_01', custom_02='custom_02', token='token')
Este método de Ecommerce
permite enviar una petición de venta a Sipay.
pay_method
:[obligatorio] Corresponde a una instanciaCard
,StoredCard
oFastPay
que indica el método de pago a utilizar.amount
: [obligatorio] Corresponde a una instancia deAmount
que representa el importe de la operación.order
: [opcional] Es unstring
que representa el ticket de la operación.reconciliation
: [opcional] Es unstring
que identifica la conciliación bancaria.custom_01
: [opcional] Es unstring
que representa un campo personalizable.custom_02
: [opcional] Es unstring
que representa un campo personalizable.token
: [opcional] Es unstring
que representa un token a almacenar. Se utiliza cuando el método de pago es de tipoCard
oFpay
, y se desea asignar un token específico a la tarjeta utilizada.
El método authorization
devuelve un objeto Authorization
.
- Autorización con tarjeta
from sipay.paymethod.card import Card
from sipay.amount import Amount
amount = Amount(100, 'EUR') # 1€
card = Card('4242424242424242', 2050, 2)
auth = ecommerce.authorization(card, amount)
- Autorización con FastPay
from sipay.paymethod.fastpay import FastPay
from sipay.amount import Amount
amount = Amount(100, 'EUR') # 1€
fp = FastPay('830dc0b45f8945fab229000347646ca5')
auth = ecommerce.authorization(fp, amount)
Este método permite enviar una petición de cancelación a Sipay.
transaction_id
: [obligatorio] Es unstring
con el identificador de la transacción.
El método cancellation
devuelve un objeto Cancellation
.
- Cancelación de operación
cancel = ecommerce.cancellation('transaction_id')
5.2.3 refund(identificator, amount, order='order', reconciliation='reconciliation', custom_01='custom_01', custom_02='custom_02', token='token')
Este método Ecommerce
permite enviar una petición de devolución a Sipay.
identificator
: [obligatorio] Es una instancia del método de pago (Card
,StoredCard
oFastPay
) o, unstring
que representa el identificador de transacción.amount
: [obligatorio] Corresponde a una instancia deAmount
con el importe de la operación.order
: [opcional] Es unstring
que representa el número de ticket o boleta de la operación.reconciliation
: [opcional] Es unstring
que identifica la conciliación bancaria.custom_01
: [opcional] Es unstring
que representa un campo personalizable.custom_02
: [opcional] Es unstring
que representa un campo personalizable.token
: [opcional] Corresponde a unstring
que representa un token a almacenar. Se utiliza cuando el identificador es de tipoCard
oFastPay
, y se desea asignar un token específico para la tarjeta utilizada.
El método refund
devuelve un objeto Refund
.
- Devolución con tarjeta
from sipay.paymethod.storedcard import StoredCard
from sipay.amount import Amount
amount = Amount(100, 'EUR') # 1€
card = StoredCard('bd6613acc6bd4ac7b6aa96fb92b2572a')
refund = ecommerce.refund(card, amount)
- Devolución con transaction_id
from sipay.amount import Amount
amount = Amount(100, 'EUR') # 1€
refund = ecommerce.refund('transaction_id', amount)
Este método Ecommerce
permite enviar una petición a Sipay para buscar de una operación concreta.
El método requiere al menos uno de los siguientes parámetros:
order
: [opcional]string
que representa el ticket de la operación.transaction_id
: [opcional]string
que representa el identificador de la transacción.
El método query
devuelve un objeto Query
.
- Búsqueda de transacciones
query = ecommerce.query(order='order')
query = ecommerce.query(transaction_id='transaction_id')
Este método Ecommerce
permite enviar una petición de tokenización de tarjeta a Sipay.
card
: [obligatorio] Instancia de tipoCard
con la tarjeta a tokenizar.token
:[obligatorio]string
que representa el token que se asociará a la tarjeta.
El método register
devuelve un objeto Register
.
- Registro de tarjeta
from sipay.paymethod.card import Card
card = Card('4242424242424242', 2050, 2)
masked_card = ecommerce.register(card, 'newtoken')
Este método Ecommerce
permite enviar una petición a Sipay con la finalidad de obtener información de una tarjeta que está tokenenizada.
token
:[obligatorio]string
que representa el token asociado a la tarjeta.
El método card
devuelve un objeto Card
del apartado Responses.
- Búsqueda de tarjeta
masked_card = ecommerce.card('newtoken')
Este método Ecommerce
permite enviar una petición a Sipay con la finalidad de dar de baja una tarjeta tokenizada.
token
:[obligatorio]string
que representa el token asociado a la tarjeta.
El método unregister
devuelve un objeto Unregister
.
- Borrar una tarjeta del registro
unregister = ecommerce.unregister('token')
5.2.8 preauthorization(paymethod, amount, order='order', reconciliation='reconciliation', custom_01='custom_01', custom_02='custom_02', token='token')
Este método de Ecommerce
permite enviar una petición de preautorización a Sipay.
pay_method
:[obligatorio] Corresponde a una instanciaCard
,StoredCard
oFastPay
que indica el método de pago a utilizar.amount
: [obligatorio] Corresponde a una instancia deAmount
que representa el importe de la operación.order
: [opcional] Es unstring
que representa el ticket de la operación.reconciliation
: [opcional] Es unstring
que identifica la conciliación bancaria.custom_01
: [opcional] Es unstring
que representa un campo personalizable.custom_02
: [opcional] Es unstring
que representa un campo personalizable.token
: [opcional] Es unstring
que representa un token a almacenar. Se utiliza cuando el método de pago es de tipoCard
oFpay
, y se desea asignar un token específico a la tarjeta utilizada.
El método preauthorization
devuelve un objeto Preauthorization
.
- Preautorización con tarjeta
from sipay.paymethod.card import Card
from sipay.amount import Amount
amount = Amount(100, 'EUR') # 1€
card = Card('4242424242424242', 2050, 2)
preauth = ecommerce.preauthorization(card, amount)
- Preautorización con FastPay
from sipay.paymethod.fastpay import FastPay
from sipay.amount import Amount
amount = Amount(100, 'EUR') # 1€
fp = FastPay('830dc0b45f8945fab229000347646ca5')
preauth = ecommerce.preauthorization(fp, amount)
5.2.9 confirmation(identificator, amount, order='order', reconciliation='reconciliation', custom_01='custom_01', custom_02='custom_02')
Este método Ecommerce
permite enviar una petición de confirmación sobre una preautorización a Sipay.
identificator
: [obligatorio] Puede ser o bien unstring
con el identificador de la transacción o una instacia de la clase Preautorizaciónamount
: [obligatorio] Corresponde a una instancia deAmount
con el importe de la operación.order
: [opcional] Es unstring
que representa el número de ticket o boleta de la operación.reconciliation
: [opcional] Es unstring
que identifica la conciliación bancaria.custom_01
: [opcional] Es unstring
que representa un campo personalizable.custom_02
: [opcional] Es unstring
que representa un campo personalizable.
El método confirmation
devuelve un objeto Confirmation
.
- Confirmación con transaction_id
from sipay.amount import Amount
amount = Amount(100, 'EUR') # 1€
conf = ecommerce.confirmation('transaction_id', amount)
- Confirmación con una instancia de Preautorización
from sipay.amount import Amount
conf = ecommerce.confirmation('preauth.transaction_id', amount)
Este método Ecommerce
permite enviar una petición de desbloqueo sobre una preautorización a Sipay.
identificator
: [obligatorio] Puede ser o bien unstring
con el identificador de la transacción o una instacia de la clase Preautorizaciónamount
: [obligatorio] Corresponde a una instancia deAmount
con el importe de la operación.order
: [opcional] Es unstring
que representa el número de ticket o boleta de la operación.custom_01
: [opcional] Es unstring
que representa un campo personalizable.custom_02
: [opcional] Es unstring
que representa un campo personalizable.
El método unlock
devuelve un objeto Unlock
.
- Desbloqueo con transaction_id
unlock = ecommerce.unlock('transaction_id', amount)
- Desbloqueo con una instancia de Preautorización
from sipay.amount import Amount
unlock = ecommerce.unlock('preauth.transaction_id', amount)
Todos los objetos obtenidos como respuestas de operativas Ecommerce
tienen los siguientes atributos.
type
: Es unenum[string]
que identifica el tipo de respuesta:- success
- warning
- error
code
: Es unint
con el código identificador del resultado. Es un código orientativo y no está ligado estrictamente con motivo de la respuesta, es decir, el código no identifica unívocamente la respuesta.- si
code
es0
, implica que el resultado es un success - si
code
es mayor a0
, implica que el resultado es un warning - si
code
es menor a0
, implica que el resultado es un error
- si
detail
: Es unstring
con el código alfanumérico separado con guiones bajos y sin mayúsculas que identifica unívocamente la respuesta. Útil para la gestión de los diferentes casos de uso de una operación.description
: Es unstring
con la descripción literal del mensaje de respuesta.uuid
: Es unstring
con el identificador único de la petición, imprescindible para la trazabilidad.request_id
: Es unstring
utilizado en la finalización de algunas operaciones. Se indicarán aquellas en las que sea necesario._request
: Es undictionary
que contiene los datos de la petición que se ha hecho al servidor._response
: Es undictionary
que contiene los datos 'raw' de respuesta.
Este objeto añade los siguientes atributos:
amount
: Objeto de de tipoAmount
con el importe de la operación.order
: Es unstring
con el ticket de la operación.card_trade
: Es unstring
que describe el emisor de la tarjeta.card_type
: Es unstring
con el tipo de la tarjeta.masked_card
: Es unstring
con el número de la tarjeta enmascarado.reconciliation
: Es unstring
identificador para la conciliación bancaria (p37).transaction_id
: Es unstring
identificador de la transacción.aproval
: Es unstring
con el código de aprobación de la entidad.authorizator
: Es unstring
con la entidad autorizadora de la operación.
Este objeto añade los atributos:
amount
Objeto de tipoAmount
con el importe de la operación.order
: Es unstring
con el ticket de la operación.card_trade
: Es unstring
con el emisor de la tarjeta.card_type
: Es unstring
con el tipo de la tarjeta.masked_card
: Es unstring
con con el número de la tarjeta enmascarado.reconciliation
: Es unstring
identificador para la conciliación bancaria (p37).transaction_id
: Es unstring
identificador de la transacción.aproval
: Es unstring
con el código de aprobación de la entidad.authorizator
: Es unstring
con la entidad autorizadora de la operación.
Este objeto añade una lista de transacciones, cada objeto transacción tiene:
Transaction
description
: Es unstring
con descripción literal del estado de la operación.date
: Es undatetime
con fecha y hora de la operación.order
: Es unstring
con el ticket de la operación.masked_card
: Es unstring
con el número de la tarjeta enmascarado.operation_name
: Es unstring
con el nombre literal del tipo de operación.operation
: Es unstring
identificador del tipo de operación.transaction_id
: Es unstring
identificador de la transacción.status
: Es unstring
identificador del estado de la operación.amount
: Es un objetoAmount
con el importe de la operación.authorization_id
: Es unstring
identificador de la entidad autorizadora.channel_name
: Es unstring
con el nombre literal del canal de pago.channel
: Es unstring
identificador del canal de pago.method
: Es unstring
identificador del método de pago.method_name
: Es unstring
identificador literal del método de pago.
Este objeto añade los siguientes atributos:
card_mask
: Es unstring
con el número de la tarjeta enmascarado.expired_at
: Es undate
con fecha de la expiración.token
: Es unstring
identificador de la tarjeta.card
: Es un objetoStoredCard
con la tarjeta asociada.
Este objeto no añade nada a lo indicado en los atributos comunes.
Este objeto añade los siguientes atributos:
card_mask
: Es unstring
con el número de la tarjeta enmascarado.expired_at
: Parámetro de tipodate
con la fecha de expiración de la tarjeta.token
: Es unstring
identificador de la tarjeta.card
: Objeto de tipoStoredCard
con los datos asociados a la tarjeta devuelta.
Este objeto no añade nada a lo descrito en los atributos comunes.
Este objeto añade los siguientes atributos:
amount
: Es un objetoAmount
con el importe de la operación.order
: Es unstring
con el ticket de la operación.reconciliation
: [opcional] Es unstring
que identifica la conciliación bancaria.card_trade
: Es unstring
con el emisor de la tarjeta.card_type
: Es unstring
con el tipo de la tarjeta.transaction_id
: Es unstring
identificador de la transacción.card_mask
: Es unstring
con el número de la tarjeta enmascarado.aproval
: Es unstring
con el código de aprobación de la entidad.authorizator
: Es unstring
con la entidad autorizadora de la operación.token
: Es unstring
identificador de la tarjeta.
Este objeto añade los siguientes atributos:
amount
: Es un objetoAmount
con el importe de la operación.order
: Es unstring
con el ticket de la operación.reconciliation
: [opcional] Es unstring
que identifica la conciliación bancaria.card_trade
: Es unstring
con el emisor de la tarjeta.card_type
: Es unstring
con el tipo de la tarjeta.transaction_id
: Es unstring
identificador de la transacción.card_mask
: Es unstring
con el número de la tarjeta enmascarado.aproval
: Es unstring
con el código de aprobación de la entidad.authorizator
: Es unstring
con la entidad autorizadora de la operación.sequence
: Es unstring
con la secuencia de la operación.
Este objeto añade los siguientes atributos:
order
: Es unstring
con el ticket de la operación.transaction_id
: Es unstring
identificador de la transacción.reconciliation
: [opcional] Es unstring
que identifica la conciliación bancaria.