Documentación integración WANNME

1. Introducción

Bienvenidos a la documentación de integración de WANNME. Durante estas páginas explicaremos los distintos modos de integración con nuestra plataforma. Esta documentación está destinada a técnicos y desarrolladores que quieran integrarse con WANNME.

Disponemos de dos formas de comunicación con nuestro sistema: la integración a través de componentes Web Javascript (ponerse en contacto con Wannme) y un APIREST securizado para la comunicación entre sistemas.

Ponemos a disposición de los portales de comercio electrónico basados en algún CMS módulos de pago o plugins para la integración con WANNME.

2. Autenticación

2.1. Credenciales

Es necesario ponerse en contacto con WANNME para la obtención de las credenciales de operación. Estas credenciales son únicas por empresa colaboradora y entorno (sandbox / producción).

  • Usuario web
  • Contraseña web
  • Partner Id
  • Clave privada
  • APIKEY de acceso al APIREST

2.2. Entornos

Disponemos de dos entornos, un entorno de sandbox y un entorno de producción. Todas nuestras URL están disponibles a través de HTTPS.

El entorno de sandbox está dedicado a pruebas durante el proceso de desarrollo de las integraciones con las empresas colaboradoras. En este entorno tanto los datos como las transacciones no son reales, siendo siempre utilizados datos de pruebas que se destruyen cada cierto tiempo.

https://rest-demo.wannme.com/integration/v2

Documentación técnica del sandbox

https://rest-demo.wannme.com/integration/v2/swagger-ui/index.html

En el entorno de producción tanto los datos como las operaciones son reales.

https://rest.wannme.com/integration/v2

2.3. Autenticación

Para asegurar la autenticación de las peticiones que se realizan al APIREST, estás deben incluir un parámetro de control checksum o resumen de la petición, compuesto por la concatenación de algunos parámetros significativos para la petición y las credenciales de acceso del comercio al APIREST codificando la cadena en SHA1. De este modo para la utlización de los end-point es necesario proporcionar una APIKEY en las cabeceras y firmar cada petición.

En los callbacks de notificaciones nuestras peticiones incluirán de igual modo al parámetro checksum, construido de igual manera. En cada notificación o end-point se especifica la forma de construir la cadena para posteriormente cifrarla con el algoritmo SHA1.

Si se envía una petición sin incluir el checksum se recibirá una respuesta con estado 400. En caso de mandar un checksum no válido para esa petición, se recibirá una respuesta con estado 500

3. Uso de la integración

A continuación se presenta una serie de listas con los datos maestros utilizados WANNME. Toda esta información se puede obtener a través de sus correspondientes end-points, por ejemplo los estados de los cobros: /wannmepay/masterdata/.

3.1. Estados de los cobros

Los cobros pueden tener los siguientes estados:

URL de consulta: integration/v2/wannmepay/masterdata/payment-states

Código Descripción
1 Creado
2 Compartido
3 Pago en proceso
4 Error
5 Pago completado
6 Medio añadido
7 Accedido
8 Pago incompleto
9 Cancelado
10 Caducado
11 Firma en proceso
12 Firma completada
13 Reembolso total

Cuando un cobro se crea figura en estado CREADO. Cuando el usuario accede al cobro se situa en estado ACCEDIDO. En el momento en el que el usuario procede al pago el cobro se situa en PAGO EN PROCESO, de donde puede transitar hacia el estado PAGO COMPLETADO o ERROR / PAGO INCOMPLETO sino ha podido pagar. El cobro se situará en estado CADUCADO si el usuario no ha realizado el pago antes de la fecha de caducidad fijada en la creación del cobro.

3.2. Sub estados de los cobros

Los cobros pueden tener los siguientes sub-estados:

Código Estado Descripción
1 Pago tarjeta Este sub estado indica que el cliente ha realizado el primer pago con tarjeta en un cobro con financiación instantánea
2 Denegada Un cobro con financiación instantánea ha sido denegado por la entidad financiera
3 Admin Este sub estado indica el autor de la cancelación de un cobro
4 Financiación completada Este sub estado indica que el cliente ha finalizado el pago de sus cuotas en un cobro con financiación instantánea
5 Punto venta Este sub estado indica el autor de la cancelación de un cobro
6 Pendiente verificación Este sub estado indica que un cobro en proceso se encuentra en estudio de la documentación por parte de la entidad financiera
7 Pago incompleto En el caso de domiciliaciones bancarias, el proceso no ha concluido

Los sub estados del cobro aportan más información sobre un cobro cuando se encuentra en alguna determinada etapa.

3.3. Estados de los recobros

Los recobros pueden tener los siguientes estados:

URL de consulta: integration/v2/wannmepay/masterdata/debt-case-states

Código Descripción
1 Creado
2 Cancelado
3 Error
4 En proceso
5 Finalizado

3.4. Sub estados de los recobros

Los recobros pueden tener los siguientes sub-estados:

Código Descripción
5 Cobros con error

3.5. Estados de los recurrentes

Los recurrentes pueden tener los siguientes estados:

URL de consulta: integration/v2/wannmepay/masterdata/recurrent-states

Código Descripción
1 Creado
2 Detenido
3 Cancelado
4 Finalizado
5 En proceso
6 Error

3.6. Sub estados de los recurrentes

Los recurrentes pueden tener los siguientes sub-estados:

Código Descripción
4 Cuotas con error
5 Cuotas finalizadas

3.7. URL's de notificación del cobro, recobro y recurrente

En la creación de un cobro, recobro o recurrente se puede proporcionar una URL de notificación a la que WANNME llamará en cada transición de estado de la entidad o en cada cambio que se produzca en la entidad, y se enviará por POST a la URL indicada. Se llamará a la URL de notificación antes de devolver el control en las URL de return (solo en el caso de un cobro). Esta URL puede ser configurada por defecto a nivel de partner para todos los cobros, recurrentes o recobro o bien se puede indicar en cada generación de entidad.

Por ejemplo, un cobro que se crea y se comparte recibe la notificación de creado y la notificación de compartido, si se volviera a compartir se generaría otra notificación de compartido. Es decir, se pueden producir notificaciones en el cambio de estado, pero también dentro de cada estado se pueden notificar eventos con el mismo estado. Otro ejemplo sería cuando se completa un pago se notificaría la transación de en proceso a completado, pero también se notificará en el estado completado la liquidación de ese cobro.

En caso de utilizar una dirección de notificación, si esta fuese una redirección debe de compartir protocolo con el origen y el destino.

La información enviada en las notificaciones de cobro es la siguiente:

{
  "id": "1600329190190828548",
  "receiptNumber":"1600329190190828548",
  "amount": 50,
  "checksum": "8b8478cc8e4b14076135183bca4e88653cf848ce",
  "statusCode": 1,
  "statusDescription": "CREADO",
  "subStatusCode": 0,
  "subStatusDescription": "xxxxxx",
  "partnerReference1": "ref1",
  "partnerReference2": "",
  "uniqueNotificationId": "1600329388963",
  "recurrentPaymentId":"",
  "debtCaseId":"",
  "errorCode":"",
  "errorDescription":"",
  "paymentMethod":""
}

checksum SHA1(id + uniqueNotificationId + partnerReference1 + clave_privada)

La información enviada en las notificaciones de recobro es la siguiente:

{
  "id": "1600329190190828548",
  "checksum": "8b8478cc8e4b14076135183bca4e88653cf848ce",
  "statusCode": 1,
  "statusDescription": "CREADO",
  "subStatusCode": 0,
  "subStatusDescription": "xxxxxx",
  "partnerReference1": "ref1",
  "partnerReference2": "",
  "uniqueNotificationId": "1600329388963"  
}

checksum SHA1(id + uniqueNotificationId + partnerReference1 + clave_privada)

La información enviada en las notificaciones de recurrente es la siguiente:

{
  "id": "1600329190190828548",
  "checksum": "8b8478cc8e4b14076135183bca4e88653cf848ce",
  "statusCode": 1,
  "statusDescription": "CREADO",
  "subStatusCode": 0,
  "subStatusDescription": "xxxxxx",
  "partnerReference1": "ref1",
  "partnerReference2": "",
  "uniqueNotificationId": "1600329388963",
  "debtCaseId":"",
}

checksum SHA1(id + uniqueNotificationId + partnerReference1 + clave_privada)

3.8. URL's de vuelta de cobros

En la creación de un cobro se pueden proporcionar URL's de vuelta (redirección) para los estados de pago correcto o pago con error. WANNME devolverá el control a estas URL's una vez se produzca el pago por parte de cliente tanto en la situación de OK como de KO. Estas URL's desde su creación deben de ir informadas con el identificador necesario para localizar en el sistema destino la entidad relacionada, esto debe hacerse en el query string, puesto que son redirecciones sin cuerpo. Estas URL's pueden ser configuradas por defecto a nivel de partner para todos los cobros o bien se pueden indicar en cada generación de un cobro.

3.9. URL's de notificación de método de pago de punto de venta (merchant)

En la inicializacón de un método de pago de un punto de venta (merchant), se puede proporcionar una URL de notificación a la que WANNME llamará en cada transición de estado del método de pago, y se enviará por POST a la URL indicada información de la transición.

La información enviada en las notificaciones es la siguiente:

{
    "partnerId": "ivj-5xbk741t57zxry9k",
    "checksum": "d8ed9f8f2b58dfc9e0f9357e504b4c3d894417c7",
    "paymentMethod": "payin7",
    "active": false,
    "stateId": "5",
    "stateName": "Esperando firma del comercio",
    "merchantReference1": "merchantReference1",
    "merchantReference2": "merchantReference1",
    "uniqueNotificationId": "1619012820038"
}

checksum SHA1(partnerId + uniqueNotificationId + paymentMethod + clave_privada)

3.10. Datos maestros

A continuación presentamos algunos datos maestros que estan disponibles a través de los end-point de maestros en el api.

Tipos de documento

Los documentos pueden ser de los siguientes tipos:

URL de consulta: integration/v2/wannmepay/masterdata/document-types

Código Descripción
1 DNI
2 Pasaporte
3 CIF
4 Tarjeta de residencia

Tipos de intervalos de recurrencia

Los intervalos pueden ser de los siguientes tipos:

URL de consulta: integration/v2/wannmepay/masterdata/recurrent-interval-types

Código Descripción
1 Cada día
2 Cada semana
3 Cada mes
4 Cada 3 meses
5 Cada 6 meses
6 Cada año
7 Personalizado

Tipos de gestión de recobro

Las gestiones pueden ser de los siguientes tipos:

URL de consulta: integration/v2/wannmepay/masterdata/debt-case-management-types

Código Descripción
1 Amistoso
2 Judicial

Tipos de estados judiciales de un recobro

Los estados judiciales pueden ser de los siguientes tipos:

URL de consulta: integration/v2/wannmepay/masterdata/debt-case-judicial-state-types

Código Descripción
1 Monitorio
2 Verbal
3 Ejecución
4 Ordinario

Métodos de pago de un cobro

Cuando se crea un cobro es posible indicar que en el proceso de checkout del cobro únicamente aparezcan algunos métodos de pago, y no todos los que tiene contratado el punto de venta con WANNME. Esto se hace a través del atributo paymentMethods que permite una lista de alguno/s de los siguientes valores. Sino se indica ningún valor, en el checkout aparecerán todos los métodos, si se especifica algun/os valor/es, únicamente aparecerán esos, si están contratados en WANNME.

Valor Descripción
payin7 Payin7
redsys RedSys
bizum Bizum
abanca Abanca
slimpay_direct_debit SlimPay Domiciliación
afterbanks AfterBanks
cecabank Cecabank

Tipos vías

Los tipos de vías pueden ser de los siguientes:

URL de consulta: integration/v2/wannmepay/masterdata/via-types

Código Descripción
1 Alameda o aldea
2 Apartamento
3 Avenida
4 Bloque
5 Barrio
6 Chalet
7 Calle
8 Camino
9 Colonia
10 Carretera
11 Caserio
12 Cuesta
13 Edificio
14 Glorieta
15 Grupo
16 Lugar
17 Mercado
18 Municipio
19 Manzana
20 Poblado
21 Poligono
22 Pasaje
23 Parque
24 Prolongacion
25 Paseo
26 Plaza
27 Rambla
28 Ronda
29 Travesia
30 Urbanizacion
31 Desconocida, Apartado de correos
32 Bajada
33 Rua
34 Subida

Provincias

Las provincias pueden ser de los siguientes:

URL de consulta: integration/v2/wannmepay/masterdata/provinces

Código Descripción
1 ÁLAVA
2 ALBACETE
3 ALICANTE
4 ALMERÍA
5 ÁVILA
6 BADAJOZ
7 ILLES BALEARS
8 BARCELONA
9 BURGOS
10 CÁCERES
11 CÁDIZ
12 CASTELLÓN
13 CIUDAD REAL
14 CÓRDOBA
15 A CORUÑA
16 CUENCA
17 GIRONA
18 GRANADA
19 GUADALAJARA
20 GUIPUZKOA
21 HUELVA
22 HUESCA
23 JAÉN
24 LEÓN
25 LLEIDA
26 LA RIOJA
27 LUGO
28 MADRID
29 MÁLAGA
30 MURCIA
31 NAVARRA
32 OURENSE
33 ASTURIAS
34 PALENCIA
35 LAS PALMAS
36 PONTEVEDRA
37 SALAMANCA
38 STA. CRUZ DE TENERIFE
39 CANTABRIA
40 SEGOVIA
41 SEVILLA
42 SORIA
43 TARRAGONA
44 TERUEL
45 TOLEDO
46 VALENCIA
47 VALLADOLID
48 BIZKAIA
49 ZAMORA
50 ZARAGOZA
51 CEUTA
52 MELILLA

3.11. Uso de expedientes recurrentes

En el API de integración presentamos métodos para la gestión de los expedientes recurrentes de tipo suscripción y plan de pagos. La diferencia entre la suscripción y el plan de pagos es que la suscripción permite la generación de cobros de importe igual y periodicidad constante, mientras que los planes de pago permiten la generación de cobros planificados o no, de cantidades distintas y periodicidades también distintas.

Una vez creado el expediente recurrente, debe de ser inicializado a través de la acción initialize, lo que permite comenzar el ciclo de recurrencia con un primer cobro que el cliente debe completar para almacenar el método de pago y así poder ejecutar los cobros planificados.

Un recurrente en proceso puede ser detenido, reaunudado o cancelado, lo que supone la suspensión o reactivación del ciclo de recurrencia.

En el API se dispone de métodos para reintentar un cobro de un expediente recurrente en estado de error, o realizar un cobro manual en una suscripción, lo que permite en cualquier momento sobre el método de pago almacenado generar y ejecutar un cobro por un importe distinto al marcado en la suscripción.

3.12. Estados de los merchant

Los diferentes valores que se pueden presentar en el atributo stateId de un merchant son los siguientes:

Código Nombre Descripción
1 Datos no cargados El merchant no dispone de toda la información necesaria para comenzar el proceso de verificación de esos datos por parte de WANNME.
2 Verificación en proceso Los datos del merchant están siendo analizados por WANNME. Del mismo modo un merchant en estado operativo puede volver a este estado si sus datos son modificados y no validados por WANNME
3 Firma en proceso El merchant debe completar los procesos de firma solicitados si existiesen
4 Operativo El merchant está disponible para las operativas de negocio en WANNME

Cuando un merchant es creado o modificado se evalúa su información hasta que se sitúe en el estado de verificación. Será WANNME el que valide la documentación aportada y transitará el merchant a un estado operativo. En los entornos de sandbox existe un endpoint para poder realizar esta transicción de forma manual.

3.13. Estados de los métodos de pago de un merchant

Los diferentes valores que se pueden presentar en el atributo stateId de un método de pago de un merchant son los siguientes:

Código Descripción
1 Sin solicitar
2 Solicitado por comercio
3 Solicitado contrato a proveedor
4 Faltan datos comercio
5 Esperando firma del comercio
6 Esperando activación en proveedor
7 Servicio activado en proveedor
8 Servicio desactivado en proveedor
9 Firmado por comercio
10 Servicio activado por cuenta del comercio
11 Servicio activado en proveedor (solicitado cambio IBAN)

4. Integración APIREST

Para el uso de los end-point proporcionados por WANNME es necesario situar la KEY proporcionada en las cabeceras de la llamada. El tipo de cabecera a usar es:

Authorization KEY

De no utilizar una credencial valida el sistema responderá con un estado 401 Unauthorized. Estas KEYs tienen una caducidad de un año sin usarse.

Se establece otro sistema de seguridad a partir del resumen de determinados datos de la llamada a cada end-point con un algoritmo de resumen.

Algunos ejemplos del API-REST para Postman se pueden descargar aqui Collection Environment

4.1. Gestión de cobros

Ponemos a disposición de los desarrolladores diversos métodos para la creación y manipulación de cobros en el sistema WANNME. Se pueden crear y actualizar los cobros, así como recuperar la información asociada a los mismos. En el Swagger se encuentra la información necesaria para proporcionar el checksum de cada llamada.

Algunas consideraciones sobre el cobro:

  • Para la creación del cobro es necesario proporionar de forma obligatoria los campos partnerId, checksum, amount y partnerReference1
  • checksum SHA1(partnerId + clave_privada + amount + partnerReference1)
  • El campo partnerReference2 es opcional, y junto con el campo partnerReference1 son los identificadores del comercio que permiten localizar el cobro en tu sistema, deben de ser únicos
  • Es posible definir a nivel de punto de venta las direcciones de notificación y de retorno OK y KO para no enviarlas en cada creación de cobro. Se examina primero la creación, si existen URL’s se usarán las de la creación, sino se utilizarán las definidas por punto de venta si existen
  • El parámetro manualPayment configura el cobro manual. Si manualPayment se activa a true, no se enviarán sms ni email, si se activa a false los parámetros sendSMS y sendEmail se utilizarán según sean proporcionados

Del mismo modo se disponen de varias acciones:

  • cancel: permite cancelar un cobro existente
  • share: permite compartir el cobro y enviar las notificaciones al cliente (sms, email, etc.)
  • total-refund: permite realizar una devolución completa del cobro si es posible

Cobro: Objeto payment

{
  "partnerId": "partnerId_comercio",
  "checksum": "campo_calculado",
  "amount": 400.44,
  "description": "",
  "mobilePhone": "656440812",
  "mobilePhone2": "",
  "mobilePhone3": "",
  "email": "email@cliente.com",
  "email2": "",
  "email3": "",
  "expirationDate" : "2021-01-23T12:34:56.123456789Z",
  "partnerReference1" : "referencia_externa_comercio",
  "partnerReference2": "",
  "notificationURL": "",
  "returnOKURL" : "",
  "returnKOURL" : "",
  "paymentMethods": ["bizum","redsys"],
  "usersGroup": "",
  "customer" : {
    "address": "",
    "bankAccountIban": "",
    "document": "",
    "documentType": 0,
    "firstName": "",
    "floorStairsDoor": "",
    "lastName1": "",
    "lastName2": "",
    "location": "",
    "postalCode": "",
    "provinceType": 0,
    "viaType": 0
  },
  "extra" :  {
    "manualPayment": false,
    "paymentPassword": "",
    "sendCertifiedSMS": false,
    "sendEmail": false,
    "sendSMS": false,
    "tokenizeOnly": false
  }
}

4.2. Gestión de recobros

Ponemos a disposición de los desarrolladores diversos métodos para la creación y manipulación de recobros en el sistema WANNME. Se pueden crear y actualizar los recobros, así como recuperar la información asociada a los mismos. En el Swagger se encuentra la información necesaria para proporcionar el checksum de cada llamada.

Los recobros permiten la gestión de los intervinientes y de los cobros asociados al proceso de recobro.

Se puede configurar el recobro con los siguientes atributos en tiempo de creación:

  • sendPaymentAllMobilePhones: se enviará la notificación de los cobros a todos los teléfonos configurados en el recobro, sino está activa esta propiedad solo se enviará al teléfono principal
  • sendPaymentAllEmails: se enviará la notificación de los cobros a todos los emails configurados en el recobro, sino está activa esta propiedad solo se enviará al teléfono principal
  • createTotalAmountPaymentAuto: en tiempo de creación esta propiedad permite la creación automática de un cobro por la totalidad del recobro
  • sendPaymentAuto: en caso de estar activada la propiedad createTotalAmountPaymentAuto, se permite el envío automático de las notificaciones por sms, email.
  • requestCustomerDocumentInPayment: se solicitará al cliente el DNI como contraseña para acceso a los cobros

Del mismo modo se disponen de varias acciones:

  • cancel: permite cancelar un recobro existente

Recobro: Objeto debt-case

{
  "partnerId": "partnerId_comercio",
  "checksum": "campo_calculado",
  "amountTotalDebt": 500,
  "amountPrincipalDebt": 50,
  "amountPending": 490,
  "amountRealDiscount": 10,
  "amountMaximumDiscount": 20,
  "amountMinimumPartialPayment": 30,
  "amountExternalPayment": 0,
  "description": "",
  "mobilePhone1": "",
  "mobilePhone2": "",
  "mobilePhone3": "",
  "email1": "",
  "email2": "",
  "email3": "",
  "dueDate" : "",
  "partnerReference1" : "",
  "partnerReference2": "",
  "documentURL1": "",
  "documentURL2": "",
  "documentURL3": "",
  "usersGroup" : "",
  "notificationURL":"",
  "mainCustomer" : {
    "address": "",
    "bankAccountIban": "",
    "document": "",
    "documentType": 0,
    "firstName": "",
    "floorStairsDoor": "",
    "lastName1": "",
    "lastName2": "",
    "location": "",
    "postalCode": "",
    "provinceType": 0,
    "viaType": 0
  },
  "creditor" : {
    "bankAccountHolderName": "",
    "bankAccountIban": "",
    "bankAccountSwift": "",
    "brandName": "",
    "debtCaseManagementType": 0,
    "document": "",
    "documentType": 0,
    "judicialStateType": 0,
    "name": ""
  },
  "extra" : {
      "sendPaymentAllMobilePhones" : false,
      "sendPaymentAllEmails" : false,
      "createTotalAmountPaymentAuto" : false,
      "sendPaymentAuto" : false,
      "requestCustomerDocumentInPayment" : false   
  }
}

Objeto debt-case-customer

{
  "mobilePhone1": "",
  "mobilePhone2": "",
  "mobilePhone3": "",
  "email1": "",
  "email2": "",
  "email3": "",
  "documentType": 0,
  "document": "",
  "firstName": "",
  "lastName1": "",
  "lastName2": ""
}

4.3. Gestión de cobros recurrentes

Ponemos a disposición de los desarrolladores diversos métodos para la creación y manipulación de cobros recurrentes en el sistema WANNME. Se pueden crear y actualizar los cobros recurrentes, así como recuperar la información asociada a los mismos. En el Swagger se encuentra la información necesaria para proporcionar el checksum de cada llamada.

Para la creación de un cobro recurrente es necesario proporcionar un tipo de periodicidad, es decir una frecuencia de recurrencia. Cuando el cobro recurrente ha sido creado y configurado correctamente, debe de utilizarse la acción initialize para dar comienzo al proceso de recurrencia.

No se pueden realizar modificaciones en un recurrente ya iniciado sino se detiene previamente.

Del mismo modo se disponen de varias acciones:

  • cancel: permite cancelar un cobro recurrente existente
  • initialize: permite inicializar un cobro recurrente
  • pause: permite detener la recurrencia del cobro recurrente
  • resume: permite reanudar la recurrencia del cobro recurrente que previamente ha sido detenido

Recurrente: Objeto recurrent-payment

{
  "partnerId": "partnerId_comercio",
  "checksum": "campo_calculado",
  "description": "",
  "mobilePhone": "",
  "mobilePhone2": "",
  "mobilePhone3": "",
  "email": "",
  "email2": "",
  "email3": "",
  "partnerReference1" : "",
  "partnerReference2": "",
  "notificationURL":"",
  "usersGroup": "string"
  "suscription" : {
    "amount":120,
    "intervalType":0,
    "startDate":"2023-01-23T12:34:56.123456789Z",
    "endDate":"2024-01-23T12:34:56.123456789Z",
    "amountFirstInstallment":33.33,
    "firstInstallmentDate":"2022-01-23T12:34:56.123456789Z"
  },
  "paymentPlan": {
    "finalizeRecurrent": false
  },
  "customer": {
    "address": "",
    "bankAccountIban": "",
    "document": "",
    "documentType": 0,
    "firstName": "",
    "floorStairsDoor": "",
    "lastName1": "",
    "lastName2": "",
    "location": "",
    "postalCode": "",
    "provinceType": 0,
    "viaType": 0
  },
  "extra": {}
}

4.4. Gestión de merchants

Ponemos a disposición de los desarrolladores diversos métodos para la creación y manipulación de Merchants en el sistema WANNME. Se pueden crear y actualizar los Merchants, así como recuperar la información asociada a los mismos. Los Merchants permiten también la gestión de los métodos de pago, como es el caso de Redsys o PayIn7. Un método de pago se pude inicializar, actualizar y desactivar. Al momento de inicializar un método de pago hay que pasar una URL de notificación, tal y como se indica en la sección 3.9. Sumado a lo ya mencionado, también es posible la personalización de la página web del PayCheckout, como es el cambio de textos, tipos de letras e imágenes, por mencionar algunos de los cambios disponibles.

La asignación de un documento a un merchant, se explica en la sección 4.5.

4.4.1 Configuración del proceso de checkout

Existe la posibilidad de activar o desactivar la personalización del proceso de checkout para los comercios creados. Por defecto, WANNME proporciona una imagen y textos para el proceso, pero es posible alterar esta configuración a través del end-point /wannmepay/merchant/{partnerId}/checkout-branding.

{
    "partnerId": "7x53juavzcx_upvh_in8_z2bp",
    "checksum": "62b7134f9b1bd13fcf6237b701025662b7931070",
    
    "checkoutBrandingActive": false,
    
    "headerBackgroundColor": null,
    "titlesTextColor": null,
    "textColor": null,
    "buttonTextColor": null,
    "buttonBackgroundColor": null,
   
    "showReceiptButton": false,
    "showSendReceiptByEmailButton": false,
    "showRequestInvoiceButton": false,
    "hideHeader": false,
    "showLanguageSelection": false,

    "footerOwnWebURL": null,
    "footerPrivacyPolicyURL": null,
    "footerCookiesURL": null,
   
    "logoDocumentId": ""    
}

4.4.2 Personalización de textos del proceso de checkout

Es posible la edición de algunos textos presentes en el Paycheckout. Llamando al end-point /wannmepay/masterdata/checkout-branding-translation-types se obtienen la lista de esos textos personalizables con una pequeña explicación de cada uno.

Además de existir esos textos personalizables, también existe la posibilidad de personalizarlos para cada uno de los idiomas disponibles en el sistema. Se pueden obtener los idiomas disponibles en el sistema llamando al end-point /wannmepay/masterdata/languages.

Para saber cuáles son esos textos personalizados en todos los idiomas disponibles asociados al punto de venta que se mostrarán en el Paycheckout, se debe llamar al end-point /wannmepay/merchant/{partnerId}/checkout-branding/translations/list. En esta llamada recibiremos todos los textos tenga o no activado el punto de venta la personalización del Paycheckout.

Si el punto de venta tiene activada la personalización del Paycheckout y quiere modificar alguno de esos textos, se hará uso del end-point /wannmepay/merchant/{partnerId}/checkout-branding/translations donde se informará para cada uno de los textos que se quiera personalizar, un texto para cada uno idioma.

{
     "partnerId": "7x53juavzcx_upvh_in8_z2bp",
     "checksum": "62b7134f9b1bd13fcf6237b701025662b7931070",
     "translations": [
        {
            "code": "commerce.info.label",
            "values": [
                {
                    "language": "de",
                    "value": "Handelsdaten"
                },
                {
                    "language": "en",
                    "value": "Merchant information"
                },
                {
                    "language": "es",
                    "value": "DATOS DEL COMERCIO"
                },
                {
                    "language": "fr",
                    "value": "DATOS DEL COMERCIO [FR]"
                },
                {
                    "language": "pt",
                    "value": "DATOS DEL COMERCIO [PT]"
                }
            ]
        },
        ................................
        {
            "code": "viacash.title",
            "values": [
                {
                    "language": "de",
                    "value": "Barzahlung "
                },
                {
                    "language": "en",
                    "value": "Cash payment"
                },
                {
                    "language": "es",
                    "value": "Pagar en efectivo"
                },
                {
                    "language": "fr",
                    "value": "Payer en espces"
                },
                {
                    "language": "pt",
                    "value": "Payer en PT"
                }
            ]
        }
    ]
}

Solo deben indicarse los que se quieran crear o modificar en cada llamada, no afectando a los creados o modificados anteriormente. Para eliminar una personalización, se debe enviar el idioma sin indicar el valor del texto personalizado.

Por ejemplo: Se quiere borrar el texto personalizado return.store.text en alemán y añadir o modificar la personalización del texto en español.

{
    "partnerId": "7x53juavzcx_upvh_in8_z2bp",
    "checksum": "62b7134f9b1bd13fcf6237b701025662b7931070",
    "translations": [
        {
            "code": "return.store.text",
            "values": [
                {
                    "language": "de"
                },
                {
                    "language": "es",
                    "value": "Volver a la tienda"
                }
            ]
        }
    ]
}

4.5. Gestión de documentos

Ponemos a disposición de los desarrolladores diversos métodos para la creación y manipulación de Documentos en el sistema WANNME. Se puede subir documentos, obtener el documento subido y eliminar el documento.

El documento se sube en Base64, y los tipos válidos son los siguientes:

  • PNG
  • PDF
  • GIF
  • JPG
  • JPEG
  • CSV

En caso que todo haya salido correctamente la respuesta será la siguiente:

{
    "partnerId": "7x53juavzcx_upvh_in8_z2bp",
    "checksum": "62b7134f9b1bd13fcf6237b701025662b7931070",
    "documentType": "MERCHANT_COMPANY_SHAREHOLDER_IDENTIFICATION_CARD",
    "content": null,
    "fileName": "genericDNI.pdf",
    "contentType": "application/pdf",
    "id": "7a1e968c17d83d5557a99d80184304534acb358b3f5ec4637f9c25877a6d6610"
}

Para asignar un documento a un punto de venta (merchant) nuevo o ya existente, se debe primero subir el documento y luego asignarlo a la propiedad correspondiente. En el ejemplo, el Id del documento fue asignado al campo: registrationDocumentId.

 "documents": 
 {
    "registrationDocumentId": "7a1e968c17d83d5557a99d80184304534acb358b3f5ec4637f9c25877a6d6610",
    "taxIdDocumentId": "0",
    "bankAccountOwnershipVerificationId": "0",
    "shareholderIdentificationCardId": "0",
    "realOwnershipDocumentId": "0"
}

4.6. Gestión de errores provocados

En los entornos de desarrollo de WANNME se pueden provocar diferentes situaciones de error para comprobar el funcionamiento de la integración ante situaciones anómalas. El funcionamiento de esta gestión de errores es proporcionar diferentes valores en algunos campos significativos como se detalla a continuación.

Valor Campo Entidad Operación
99.13 Importe Cobro Devolución total
99.14 Importe Cobro Cancelación
99.15 Importe Cobro Compartir
55.55 Importe Cobro Devolución parcial
99.16 Importe total Recobro Cancelar
99.17 Importe del cobro Recobro Crear un cobro para un recobro
9988771122Z Documento Recobro Creación de un interviniente
REF-INVOICE-ERROR Referencia Recobro Creación de una factura
99.18 Importe de la cuota Recurrente Cancelar
99.19 Importe de la cuota Recurrente Inicializar
99.20 Importe de la cuota Recurrente Detener
99.21 Importe de la cuota Recurrente Reiniciar
99.22 Importe de la cuota Recurrente Reintentar cobro

4.7. Notas integración APIREST

Cosas que debes tener en cuenta para el correcto funcionamiento de la integración:

  1. Formato de fechas: yyyy-MM-dd'T'HH:mm:ss.SSSZ
  2. El checksum se calculará como el resumen en SHA1 de la cadena especificada en cada método. (Recuerda que la clave privada debe almacenarse únicamente en tu servidor y generar de forma dinámica el checksum para cada método)
  3. Es necesario proporcionar la cabecera Authorization con la APIKEY de las credenciales para el uso del APIREST
  4. Ponemos a disposición de los desarrolladores un Swagger para la comprobación de los detalles de los end-point
  5. Es posible incluir en las cabeceras de las peticiones la clave Content-Language con un valor ISO de idioma para la obtención de los contenidos localizados en el idioma proporcionado. Los idiomas disponibles de pueden obtener en el end-point /wannmepay/masterdata/languages
  6. Los valores de tipo double especificados en los end-point usados para el proceso de firma no deben incoporar los ceros no necesarios a la derecha de la coma. Por ejemplo, el valor 33,5 es un valor distinto a 33,50 para el calculo de la firma. Es decir, los atributos de tipo double deben de ser enviados como tipo numérico y no como cadenas de caracteres, si se pasa a cadena de texto para ser enviado deben de eliminarse los ceros no significativos

5. Integración comercio electrónico

WANNME disponse de módulos o plugins para su integración en los portales de comercio electrónico o CMS, mostrando WANNME como una opción de pago más dentro del proceso de compra de los sitios web. La lista de CMS actualmente soportada por WANNME es la siguiente:

CMS Descarga plugin
Prestashop Última versión
WooCommerce Última versión

5.1. Prestashop

Versiones soportadas de PrestaShop:

  • 1.6
  • 1.7

Requisitos obligatorios:

  • PHP 7 o superior

Notas:

  • Es necesario configurar el plugin para la comprobación de las actualizaciones
  • No necesita base de datos adicional

5.2. Wordpress - WooCommerce

Requisitos obligatorios:

  • WooCommerce instalado
  • PHP 7 o superior

Notas:

  • Es necesario configurar el plugin para la comprobación de las actualizaciones
  • No necesita base de datos adicional