Integración Split Transfer
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 está disponible tanto en REST como en XML 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 PAYCOMET.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 parámetro Split Id.. Este dato se puede recuperar desde el panel de control de PAYCOMET en (Terminales -> "Nombre de terminal" -> Datos de terminal -> Credenciales de integración).
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 PAYCOMET por el Banco de España.
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 en PAYCOMET. Estos pueden ser:
execute_purchaseexecute_purchase_dccpreauthorization_confirm
2. Proceso de Split Transfer
El proceso de Split Transfer puede ser automático (se define desde PAYCOMET 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_transferaquí puedes acceder al serviciosplit_transfer_reversalaquí puedes acceder al servicio
3. Retiradas (Pay-Out)
El comercio se puede retirar los fondos a su cuenta financiera por el proceso habitual de PAYCOMET. Este puede ser automático o bajo demanda desde el panel de control de PAYCOMET en: (Configuración->Facturación->Fondos).
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.
Las tecnologías disponibles para la operativa con la pasarela de pagos PAYCOMET son SOAP y REST, ambas basadas 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 con ambos protocolos para los principales lenguajes de programación usados en entornos web.
Las peticiones se realizan mediante el protocolo de transporte HTTPS, de manera que debes asegurarte de que tu 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.
Importante
La integración XML está obsoleta. Recomendamos usar la integración REST.
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
A continuación, selecciona el tipo de integración:
La integración de esta función en REST está detallado en su documentación completa, disponible en este enlace
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,5} | 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 |
Cálculo de firma: (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)
La descripción de la columna “Contenido” se refiere a la expresión regular que debe cumplir la información presente en el elemento correspondiente (salvo en el caso de DS_ORIGINAL_IP, que se refiere a una dirección IP del tipo “192.168.1.254”). De esta manera “[A-Z]” indica cualquier carácter de la “A” a la “Z” y los corchetes indican el número de caracteres. Por ejemplo “1{2,4}” valida los números “11”, “111” y “1111”.
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
A continuación, selecciona el tipo de integración:
La integración de esta función en REST está detallado en su documentación completa, disponible en este enlace
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,5} | 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 |
Cálculo de firma: (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)
La descripción de la columna “Contenido” se refiere a la expresión regular que debe cumplir la información presente en el elemento correspondiente (salvo en el caso de DS_ORIGINAL_IP, que se refiere a una dirección IP del tipo “192.168.1.254”). De esta manera “[A-Z]” indica cualquier carácter de la “A” a la “Z” y los corchetes indican el número de caracteres. Por ejemplo “1{2,4}” valida los números “11”, “111” y “1111”.
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
A continuación, selecciona el tipo de integración:
La integración de esta función en REST está detallado en su documentación completa, disponible en este enlace
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,5} | 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 |
Cálculo de firma: (transfer)
SHA256(DS_MERCHANT_MERCHANTCODE + DS_MERCHANT_TERMINAL + DS_MERCHANT_ORDER + DS_SUBMERCHANT_TERMINAL_SPLITID + DS_SUBMERCHANT_AMOUNT + DS_SUBMERCHANT_CURRENCY + PASSWORD)
La descripción de la columna “Contenido” se refiere a la expresión regular que debe cumplir la información presente en el elemento correspondiente (salvo en el caso de DS_ORIGINAL_IP, que se refiere a una dirección IP del tipo “192.168.1.254”). De esta manera “[A-Z]” indica cualquier carácter de la “A” a la “Z” y los corchetes indican el número de caracteres. Por ejemplo “1{2,4}” valida los números “11”, “111” y “1111”.
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
A continuación, selecciona el tipo de integración:
La integración de esta función en REST está detallado en su documentación completa, disponible en este enlace
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,5} | 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 |
Cálculo de firma: (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)
La descripción de la columna “Contenido” se refiere a la expresión regular que debe cumplir la información presente en el elemento correspondiente (salvo en el caso de DS_ORIGINAL_IP, que se refiere a una dirección IP del tipo “192.168.1.254”). De esta manera “[A-Z]” indica cualquier carácter de la “A” a la “Z” y los corchetes indican el número de caracteres. Por ejemplo “1{2,4}” valida los números “11”, “111” y “1111”.
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. |