Integración Bankstore Operativa Transfer

  1. Introducción
  2. Proceso de Split Payment Transfer
    1. Proceso de cobro (Pay-In)
    2. Proceso de Split Transfer
    3. Retiradas (Pay-Out)
  3. Configuración del TPV
  4. Programación API
    1. Ejecución de un cobro execute_purchase
    2. Ejecución de un Split del pago split_transfer
    3. Devolución de un Split del pago split_transfer_reversal
    4. Ejecución de una transferencia transfer
    5. Revocación de una transferencia transfer_reversal
  5. Cálculo de la firmas

Introducción

El servicio de Split Payments se ofrece como modelo ideal para la distribución de saldos a partir de una operación de cobro realizada previamente. Este servicio utiliza BankStore como modelo de integración por lo que cualquier llamada al servicio split_transfer o split_transfer_reversal deberá tener como origen una operación realizada previamente execute_purchase, execute_purchase_dcc o preauthorization_confirm.

Esto generará un saldo en el producto desde el que se origina la transacción. Dicho saldo será el total de la transacción menos la comisión financiera que haya tenido la compra. Una vez finalizada la operación de compra se podrán mandar tantos split_transfer como se quieran a otras cuentas destino en PAYTPV.Esta operación de split_transfer se podrá ejecutar siempre que exista saldo en la cuenta del producto que generó la operación y no hayan transcurrido más de 90 días de la compra inicial.

El único dato necesario para generar un split_transfer a una cuenta destino es el DS_SUBMERCHANT_TERMINAL_SPLITID (denominado Split Id.). Este dato se puede recuperar desde el panel de control de PAYTPV en “Mis productos” -> “Configurar producto” -> Selecciona el producto destino -> “Generar Split Id”.

El dato Split Id. debe ser transmitido de forma segura al emisor de la transacción para que pueda ingresar la parte proporcional de sus servicios mediante el split_transfer después de una compra.

Este servicio es muy utilizado por Marketplaces para cobrar una sola operación al cliente final. De esta forma el Marketplace recibe el importe total de la operación y cuando el proveedor real hace la entrega del servicio o bien, este le abona mediante un split_transfer el importe total de la transacción menos su comisión. También es muy útil para cobrar comisiones por publicidad, por servicios, etc… sin que afecte al cliente final con dos cargos. Este servicio también permite el amparo legal que la legislación Europea está exigiendo respecto a la recepción de los importes por una Entidad de Pago autorizada como PAYTPV por el Banco de España.

Adjuntamos un sencillo esquema del funcionamiento de una transacción de ejemplo (100€) con una distribución en 3 comercios de PAYTPV:

Integración Split Transfer PAYTPV

Proceso de Split Payment Transfer

1. Proceso de cobro (Pay-In)

El cobro de la operación se puede realizar por cualquiera de los procesos del propio producto BankStore de PAYTPV. Estos pueden ser:

  • execute_purchase aquí puedes acceder al servicio: (por XML o por IFRAME/FULLSCREEN)
  • execute_purchase_dcc aquí puedes acceder al servicio: (por XML)
  • preauthorization_confirm aquí puedes acceder al servicio: (por XML o por IFRAME/FULLSCREEN)

2. Proceso de Split Transfer

El proceso de Split Transfer puede ser automático (se define desde PAYTPV la lógica y el cliente no cambia nada en su integración) o bajo demanda. En caso de ser bajo demanda el comercio debe ejecutar posteriormente a un pago, una operación de split_transfer para realizar un ingreso en una cuenta destinataria o un split_transfer_reversal si quiere retroceder un split_transfer ejecutado con anterioridad. Es muy importante saber que estos servicios se podrán hacer siempre y cuando exista el saldo suficiente para cubrir los importes de las transferencias.

Los dos servicios a los que se pueden llamar son:

  • split_transfer aquí puedes acceder al servicio: (por XML)
  • split_transfer_reversal aquí puedes acceder al servicio: (por XML)

3. Retiradas (Pay-Out)

El comercio se puede retirar los fondos a su cuenta financiera por el proceso habitual de PAYTPV. Este puede ser automático o bajo demanda desde el panel de control de PAYTPV "Retirada de fondos".

CONFIGURACIÓN DEL TPV

Para poder utilizar la pasarela de pago PAYTPV en su comercio deberá estar en posesión de los parámetros de configuración necesarios. Éstos pueden obtenerse a través de la plataforma de gestión de cliente de PAYTPV, en el área de cliente

Una vez dentro de la plataforma, puede revisar la configuración del producto contratado mediante el menú Mis productos->Configurar producto.

Tras pulsar en el botón “Editar” del producto elegido, aparecerá un panel con la información básica del producto bajo el apartado “Configuración técnica del TPV WEB”. En concreto los datos necesarios durante el proceso de integración son:

Para las cuentas de destino deberán generar un Split Id. (si no lo tienen generado ya). Este parámetro se puede generar/recuperar desde el panel de control de PAYTPV en “Mis productos” -> “Configurar producto” -> Selecciona el producto destino -> “Generar Split Id

Split Generado

Todas las llamadas de este servicio serán notificadas por el procedimiento habitual POST de PAYTPV. Puedes ver la información que se facilita en este enlace. La URL y/o el correo electrónico al que se recibirán las notificaciones de los servicios son configurables desde el propio panel del producto.

Programación API

Debido a que todo el proceso de pago se realiza en segundo plano (de servidor a servidor) las modificaciones a realizar en el comercio son totalmente ajenas a la experiencia de usuario.

La tecnología empleada para la operativa con la pasarela de pagos PAYTPV es SOAP, basada en HTTPS para evitar problemas de transporte a través de firewalls y otros dispositivos y a la vez garantizar la seguridad de las operaciones. Existe un soporte muy amplio para la realización de llamadas SOAP para los principales lenguajes de programación usados en entornos web.

Las peticiones se realizan mediante el protocolo de transporte HTTPS, de manera que debe asegurarse que su sistema es capaz de realizar las peticiones correctamente y gestionar los certificados de seguridad devueltos por la plataforma para una correcta utilización.

Existen varias operaciones que se podrán lanzar desde el mismo servicio. Las operaciones disponibles vienen descritas a continuación.

Ejecución de Split Transfer

Función: split_transfer

Este método permite realizar operaciones split transfer (transferencias divididas) en base a una operación de cobro previa

Las variables que se requieren para realizar un split transfer son (en este orden):

Elemento Contenido Descripción
DS_MERCHANT_MERCHANTCODE [A-Za-z0-9]{1,8} Obligatorio. Código de cliente
DS_MERCHANT_TERMINAL [0-9]{1,4} Obligatorio. Número de terminal
DS_MERCHANT_ORDER [A-Za-z0-9]{1,70} Obligatorio. Referencia de la operación de autorización original.
DS_MERCHANT_AUTHCODE [a-zA-Z0-9]{1,40} Código bancario de autorización de la transacción (necesario para ejecutar una devolución).
DS_SUBMERCHANT_TERMINAL_SPLITID [a-z0-9]{64} Identificador para recibir pagos mediante la operativa Split
DS_SUBMERCHANT_AMOUNT [0-9]{1,8} Importe de la operación en formato entero. 1,00 EURO = 100, 4,50 EUROS = 450...
DS_SUBMERCHANT_CURRENCY [EUR][USD][GBP][JPY] Moneda de la transacción. Ver más información en MONEDAS
DS_MERCHANT_MERCHANTSIGNATURE [a-zA-Z0-9]{64} Obligatorio. Ver CALCULO DE FIRMAS

La respuesta del servicio a la petición se realiza mediante la devolución de un array formateado en XML con los distintos elementos quedan descritos en la tabla siguiente:

Elemento Contenido Descripción
DS_SUBMERCHANT_AMOUNT [0-9]{1,8} Importe de la operación en formato entero. 1,00 EURO = 100, 4,50 EUROS = 450...
DS_MERCHANT_ORDER [A-Za-z0-9]{1,20} Referencia de la operación
DS_SUBMERCHANT_CURRENCY [EUR][USD][GBP][JPY] Moneda de la transacción. Ver más información en MONEDAS
DS_MERCHANT_TRANSFER_AUTHCODE [a-zA-Z0-9]{1,40} Código de autorización del split transfer, necesario para una operación de split transfer reversal
DS_RESPONSE [0-1]{1} Resultado de la operación. 0 o vacío será operación errónea y 1 operación completada.
DS_ERROR_ID [0-9]{1,5} En caso de error, aquí vendrá el código de error generado. Si no existe error vendrá 0 o vacío. Los códigos de error vienen especificados en el apartado CÓDIGOS DE ERROR.

Si la petición produjo un error de algún tipo (firma incorrecta, usuario no encontrado, etc) todos los campos se entregarán vacíos, salvo “DS_ERROR_ID” que contendrá el código de error.

En caso de que la transacción sea correcta, el servicio devolverá el campo DS_RESPONSE cuyo valor será 0 o vacío en caso de error y 1 en caso de éxito.

Ejecución de Split Transfer Reversal

Función: split_transfer_reversal

Este método permite realizar operaciones de revocación de split transfer en base a una operación de split transfer previa

Las variables que se requieren para realizar un split transfer reversal son (en este orden):

Elemento Contenido Descripción
DS_MERCHANT_MERCHANTCODE [A-Za-z0-9]{1,8} Obligatorio. Código de cliente
DS_MERCHANT_TERMINAL [0-9]{1,4} Obligatorio. Número de terminal
DS_MERCHANT_ORDER [A-Za-z0-9]{1,70} Obligatorio. Referencia de la operación de autorización original.
DS_MERCHANT_AUTHCODE [a-zA-Z0-9]{1,40} Código bancario de autorización de la transacción (necesario para ejecutar una devolución).
DS_SUBMERCHANT_TERMINAL_SPLITID [a-z0-9]{64} Identificador para recibir pagos mediante la operativa Split
DS_SUBMERCHANT_SPLIT_AUTHCODE [a-zA-Z0-9]{1,40} Código de autorización del split transfer original
DS_SUBMERCHANT_AMOUNT [0-9]{1,8} Importe de la operación en formato entero. 1,00 EURO = 100, 4,50 EUROS = 450...
DS_SUBMERCHANT_CURRENCY [EUR][USD][GBP][JPY] Moneda de la transacción. Ver más información en MONEDAS
DS_MERCHANT_MERCHANTSIGNATURE [a-zA-Z0-9]{64} Obligatorio. Ver CALCULO DE FIRMAS

La respuesta del servicio a la petición se realiza mediante la devolución de un array formateado en XML con los distintos elementos quedan descritos en la tabla siguiente:

Elemento Contenido Descripción
DS_SUBMERCHANT_AMOUNT [0-9]{1,8} Importe de la operación en formato entero. 1,00 EURO = 100, 4,50 EUROS = 450...
DS_MERCHANT_ORDER [A-Za-z0-9]{1,20} Referencia de la operación
DS_SUBMERCHANT_CURRENCY [EUR][USD][GBP][JPY] Moneda de la transacción. Ver más información en MONEDAS
DS_MERCHANT_TRANSFER_AUTHCODE [a-zA-Z0-9]{1,40} Código de autorización del split transfer, necesario para una operación de split transfer reversal
DS_RESPONSE [0-1]{1} Resultado de la operación. 0 o vacío será operación errónea y 1 operación completada.
DS_ERROR_ID [0-9]{1,5} En caso de error, aquí vendrá el código de error generado. Si no existe error vendrá 0 o vacío. Los códigos de error vienen especificados en el apartado CÓDIGOS DE ERROR.

Si la petición produjo un error de algún tipo (firma incorrecta, usuario no encontrado, etc) todos los campos se entregarán vacíos, salvo “DS_ERROR_ID” que contendrá el código de error.

En caso de que la transacción sea correcta, el servicio devolverá el campo DS_RESPONSE cuyo valor será 0 o vacío en caso de error y 1 en caso de éxito.

Ejecución de Transfer

Función: transfer

Este método permite realizar operaciones transferencia

Las variables que se requieren para realizar una transferencia son (en este orden):

Elemento Contenido Descripción
DS_MERCHANT_MERCHANTCODE [A-Za-z0-9]{1,8} Obligatorio. Código de cliente
DS_MERCHANT_TERMINAL [0-9]{1,4} Obligatorio. Número de terminal
DS_MERCHANT_ORDER [A-Za-z0-9]{1,70} Obligatorio. Referencia de la operación de autorización original.
DS_SUBMERCHANT_TERMINAL_SPLITID [a-z0-9]{64} Identificador para recibir pagos mediante la operativa Split
DS_SUBMERCHANT_AMOUNT [0-9]{1,8} Importe de la operación en formato entero. 1,00 EURO = 100, 4,50 EUROS = 450...
DS_SUBMERCHANT_CURRENCY [EUR][USD][GBP][JPY] Moneda de la transacción. Ver más información en MONEDAS
DS_MERCHANT_MERCHANTSIGNATURE [a-zA-Z0-9]{64} Obligatorio. Ver CALCULO DE FIRMAS

La respuesta del servicio a la petición se realiza mediante la devolución de un array formateado en XML con los distintos elementos quedan descritos en la tabla siguiente:

Elemento Contenido Descripción
DS_SUBMERCHANT_AMOUNT [0-9]{1,8} Importe de la operación en formato entero. 1,00 EURO = 100, 4,50 EUROS = 450...
DS_MERCHANT_ORDER [A-Za-z0-9]{1,20} Referencia de la operación
DS_SUBMERCHANT_CURRENCY [EUR][USD][GBP][JPY] Moneda de la transacción. Ver más información en MONEDAS
DS_MERCHANT_TRANSFER_AUTHCODE [a-zA-Z0-9]{1,40} Código de autorización del split transfer, necesario para una operación de split transfer reversal
DS_RESPONSE [0-1]{1} Resultado de la operación. 0 o vacío será operación errónea y 1 operación completada.
DS_ERROR_ID [0-9]{1,5} En caso de error, aquí vendrá el código de error generado. Si no existe error vendrá 0 o vacío. Los códigos de error vienen especificados en el apartado CÓDIGOS DE ERROR.

Si la petición produjo un error de algún tipo (firma incorrecta, usuario no encontrado, etc) todos los campos se entregarán vacíos, salvo “DS_ERROR_ID” que contendrá el código de error.

En caso de que la transacción sea correcta, el servicio devolverá el campo DS_RESPONSE cuyo valor será 0 o vacío en caso de error y 1 en caso de éxito.

Ejecución de Transfer Reversal

Función: transfer_reversal

Este método permite realizar operaciones de revocación de transferencia en base a una operación de transferencia previa

Las variables que se requieren para realizar una revocación de transferencia son (en este orden):

Elemento Contenido Descripción
DS_MERCHANT_MERCHANTCODE [A-Za-z0-9]{1,8} Obligatorio. Código de cliente
DS_MERCHANT_TERMINAL [0-9]{1,4} Obligatorio. Número de terminal
DS_MERCHANT_ORDER [A-Za-z0-9]{1,70} Obligatorio. Referencia de la operación de autorización original.
DS_SUBMERCHANT_TERMINAL_SPLITID [a-z0-9]{64} Identificador para recibir pagos mediante la operativa Split
DS_SUBMERCHANT_SPLIT_AUTHCODE [a-zA-Z0-9]{1,40} Código de autorización del split transfer original
DS_SUBMERCHANT_AMOUNT [0-9]{1,8} Importe de la operación en formato entero. 1,00 EURO = 100, 4,50 EUROS = 450...
DS_SUBMERCHANT_CURRENCY [EUR][USD][GBP][JPY] Moneda de la transacción. Ver más información en MONEDAS
DS_MERCHANT_MERCHANTSIGNATURE [a-zA-Z0-9]{64} Obligatorio. Ver CALCULO DE FIRMAS

La respuesta del servicio a la petición se realiza mediante la devolución de un array formateado en XML con los distintos elementos quedan descritos en la tabla siguiente:

Elemento Contenido Descripción
DS_SUBMERCHANT_AMOUNT [0-9]{1,8} Importe de la operación en formato entero. 1,00 EURO = 100, 4,50 EUROS = 450...
DS_MERCHANT_ORDER [A-Za-z0-9]{1,20} Referencia de la operación
DS_SUBMERCHANT_CURRENCY [EUR][USD][GBP][JPY] Moneda de la transacción. Ver más información en MONEDAS
DS_MERCHANT_TRANSFER_AUTHCODE [a-zA-Z0-9]{1,40} Código de autorización del split transfer, necesario para una operación de split transfer reversal
DS_RESPONSE [0-1]{1} Resultado de la operación. 0 o vacío será operación errónea y 1 operación completada.
DS_ERROR_ID [0-9]{1,5} En caso de error, aquí vendrá el código de error generado. Si no existe error vendrá 0 o vacío. Los códigos de error vienen especificados en el apartado CÓDIGOS DE ERROR.

CÁLCULO DE FIRMAS

La firma que enviará el comercio a la pasarela se calculará de la siguiente forma (en pseudo-código):

Función: (split_transfer)

SHA256(DS_MERCHANT_MERCHANTCODE + DS_MERCHANT_TERMINAL + DS_MERCHANT_ORDER + DS_MERCHANT_AUTHCODE + DS_SUBMERCHANT_TERMINAL_SPLITID + DS_SUBMERCHANT_AMOUNT + DS_SUBMERCHANT_CURRENCY + PASSWORD)

Función: (split_transfer_reversal)

SHA256(DS_MERCHANT_MERCHANTCODE + DS_MERCHANT_TERMINAL + DS_MERCHANT_ORDER + DS_MERCHANT_AUTHCODE + DS_SUBMERCHANT_TERMINAL_SPLITID + DS_SUBMERCHANT_SPLIT_AUTHCODE + DS_SUBMERCHANT_AMOUNT + DS_SUBMERCHANT_CURRENCY + PASSWORD)

Función: (transfer)

SHA256(DS_MERCHANT_MERCHANTCODE + DS_MERCHANT_TERMINAL + DS_MERCHANT_ORDER + DS_SUBMERCHANT_TERMINAL_SPLITID + DS_SUBMERCHANT_AMOUNT + DS_SUBMERCHANT_CURRENCY + PASSWORD)

Función: (transfer_reversal)

SHA256(DS_MERCHANT_MERCHANTCODE + DS_MERCHANT_TERMINAL + DS_MERCHANT_ORDER + DS_SUBMERCHANT_TERMINAL_SPLITID + DS_SUBMERCHANT_SPLIT_AUTHCODE + DS_SUBMERCHANT_AMOUNT + DS_SUBMERCHANT_CURRENCY + PASSWORD)