Skip to content

Azul Webservice Documentation

Jump to bottom
Cristopher Ortega edited this page Jun 1, 2020 · 4 revisions

Webservices AZUL permite procesar transacciones con tarjetas VISA, MasterCard, American Express, Discover y Diners. El comercio afiliado puede desarrollar una aplicacion en cualquier lenguaje de programación que soporte llamadas HTTP. Los sistemas pueden ser integrados a la plataforma de pagos de AZUL a traves del consumo de los Webservices. Webservices estan publicados en formato JSON, HTTPS Post Form y SOAP.

Nota: Para brindar la seguridad necesaria en la captura y envio de los datos hacia AZUL, el comercio deberá tener un tipo de autentificación para el formulario de tarjetas e implementar la conexión TLS 1.2.

Antes de empezar el proceso de integración/implementación, se debe establecer una comunicación segura entre el site del afiliado y el site de la plataforma de pagos de AZUL, para lo cual debe de elegirse entre:

  • VPN Site-to-Site.
  • Autenticación Mutua con Certificados Digitales emitidos localmente por AZUL.

Esta configuración debe realizarse tanto para el ambiente de pruebas como para el ambiente de producción.

Autenticación mutua con certificados digitales

Para la implementación de una comunicación segura con autenticación mutua, el afiliado debe presentar un Client Certificate emitido por AZUL (no tiene costo).

Para obtener el certificado digital primero debes generar un archivo CSR (Certificate Signing Request) y su llave (Key) de 4096 bits:

$ openssl req -new -newkey rsa:4096 -nodes -keyout your_domain.key -out your_domain.csr

Envía este archivo CSR a tu representante de AZUL, este te enviara el certificado digital que usaras para hacer requerimientos HTTP a Webservices junto con el archivo .key que creaste.

Las especificaciones con las cuales debe ser remitido el archivo CSR correspondiente son las siguientes:

Producción

Campo Valor
Common Name* URL del sitio web
Organization Name** Servicios Digitales Popular
Organization Unit Name** Produccion
Country Name** DO
State or Province** Santo Domingo
Locality Name** Distrito Nacional
Level Encryption** 4096 bits

Pruebas

Campo Valor
Common Name* URL del sitio web
Organization Name** Servicios Digitales Popular
Organization Unit Name** Desarrollo
Country Name** DO
State or Province** Santo Domingo
Locality Name** Distrito Nacional
Level Encryption** 4096 bits

* Debes indicar la URL de tu negocio (según el ambiente que se trate).

** Los archivos CSR deben llegar con estas informaciones, los valores son fijos sin importar el país o provincia en que se encuentren.

Notas Importantes

  • Los datos de pruebas y de producción nunca van a ser similares
  • Los factores de autenticación de prueba y producción nunca van a ser los mismos
  • Las URL de pruebas y Ias de producción no son las mismas

Integración

Este documento solo usa la integración con JSON. Para mas información, consulta el PDF original de AZUL.

Pruebas Producción Alternativa
https://pruebas.azul.com.do/webservices/JSON/Default.aspx https://pagos.azul.com.do/webservices/JSON/Default.aspx https://contpagos.azul.com.do/webservices/JSON/Default.aspx

Debes aplicar el header Content-Type: application/json al momento de hacer el requerimiento.

Nota: El desarrollo debe estar preparado para intentar por la URI alternativa en caso de fallar la URL principal.

Autentificación

Cada requerimiento requiere de dos valores de autenticación Auth1 y Auth2, los cuales serán entregados por AZUL durante el proceso de afiliación al servicio, el funcionamiento es similar al de un usuario/password. Debes incluir estos valores en los headers de la siguiente manera:

POST /webservices/JSON/Default.aspx
Content-Type: application/json
Auth1: usuario
Auth2: password

Los factores de autentificación para el ambiente de pruebas son diferentes a los que se les proveerá en el ambiente de producción.

Invocación

Ejemplo de un requerimiento (Sale):

curl -X POST \
  https://pruebas.azul.com.do/WebServices/JSON/Default.aspx \
  -H 'Content-Type: application/json' \
  -H 'Auth1: test' \
  -H 'Auth2: test' \
  --cert '/absolute/path/to/azul.crt' \
  --key '/absolute/path/to/azul.key' \
  -d '{
    "Channel": "EC",
    "Store": "1234567890",
    "CardNumber": {{ValidCardNumber}},
    "Expiration": {{ValidExpiration}},
    "CVC": {{ValidCVC}},
    "Amount": 650730,
    "Itbis": 99264,
    "PosInputMode": "E-Commerce",
    "TrxType": "Sale",
    "CurrencyPosCode": "$",
    "Payments": "1",
    "Plan": "0",
    "AcquirerRefData": "1",
    "RRN": null,
    "CustomerServicePhone": "809-111-2222",
    "OrderNumber": "",
    "ECommerceUrl": "yourdomain.com",
    "CustomOrderId": 1,
    "DataVaultToken": "",
    "ForceNo3DS": "1",
    "SaveToDataVault": "0"
}'

Campos de requerimiento (referencia)

Nombre Descripción
Channel Canal de pago. Este valor es proporcionado por AZUL junto a los datos de acceso a cada ambiente
Store Identificador único del comercio (MID), proporcionado por AZUL
CardNumber Numero de tarjeta. La longitud del campo se determina por la tarjeta, no se debe rellenar con ceros (O), espacios, ni caracteres especiales
Expiration Fecha expiración/vencimiento de la tarjeta Formato YYYYMM Ej: 201502
CVC Codigo de seguridad de la tarjeta (CVV2 0 CVC).
PosInputMode Modo de ingreso. Este valor es proporcionado por AZUL, junto a los datos de acceso a cada ambiente
TrxType Sale | Refund | Hold | CREATE | DELETE
Amount Monto total de la transacción (Impuestos incluidos.) Se envía sin coma ni punto. los dos últimos dígitos representan los decimales. Ei. 1000 equivale a 10.00 Ej: 1748321 equivale a 17,483.21
Itbis Valor del ITBIS. Igual formato que el campo Amount Si Ia transacción o el negocio est6n exentos, se envía en cero o simplemente no incluir en la solicitud.
CurrencyPosCode Moneda de Ia transacción Cada MID o tienda transacciona con una sola moneda. Este valor es proporcionado por AZUL, junto a los datos de acceso a cada ambiente
Payments Valor fijo: 1
Plan Valor fijo: 0
AcquirerRefData Valor fijo: 1
CustomerServicePhone Numero de servicio para atención telefónica del establecimiento. Ej: 8095442985
OrderNumber Numero de orden asociado a la transacción. Puede viajar nulo, pero siempre debe de estar
EcommerceURL Direccion web del afiliado.
CustomOrderId Numero Identificador dada por el afiliado a la transacción
AltMerchantName Campo que permite al Comercio colocar un nombre mds descriptivo para que el tarjetahabiente pueda identificarle en su estado de cuenta. Se sugiere siempre colocar su nombre comercial adecuadamente a fin de evitar disputas. Si 10 desea, puede agregar a su nombre algún indicador único de orden
DataVaultToken Valor del token generado por SDP en caso de que se desee realizar una transaccion con dicho token. Si se manda el valor de esto, no se deben enviar los valores de CardNumber, Expiration. El envio de CVC si es ecommerce puede ser o no mandatorio depende de 10 conversado con Negocios SDP. Si es MOTO la transacción, no se debería enviar CVC.
SaveToDataVault Valores posibles 1 = si, 2 = no. Si se manda este valor en 1, SDP le devolverá el token generado en el campo DataVaultToken
ForceNo3DS Valores posibles 0 =no, 1 = Si. Si se manda el valor en 0, el servicio 3D Secure hace el Challenge. Si envía el valor 1, no se realiza el Challenge.

Campos de respuesta (referencia)

Nombre Descripción
AuthorizationCode Código de autorizacion generado por el centro autorizador para la transacción. Solo presente si la transacción fue aprobada. ISOCode=ISO8583 y ResponseCode=0
CustomOrderID Numero Identificador dada por el afiliado a la transacción. Si no fue provisto en la transacción, este campo viaja en blanco
DateTime Fecha y hora de la transacción. Formato YYYYMMDDHHMMSS
ErrorDescription Descripcion del error. Valor solo presente si la transacción produjo un error. En caso de no presentar error ese campo viaja en blanco
ISOCode Codigo ISO-8583 recibido de respuesta.
LotNumber Numero de lote en que se registro la transacción
RRN Numero de referencia (Reference Referral Number).
AzulOrderld # de orden SDP. Puede ser usado en vez del RNN para generar una devolucion. Importante dar prioridad a este valor sobre el RNN.
ResponseCode Código de respuesta. Puede contener uno de los siguientes valores: Is08583 = la transacción fue procesada. Se debe revisar el campo ISOCode para ver la respuesta de la transacción Error = La transacción no fue procesada.
ReponseMessage Mensaie de respuesta ISO-8583. Valor solo presente si el ResponseCode = ISO8583
Ticket Numero del ticket correspondiente a la transacción
CardNumber Tarjeta usada para la transacción, enmascarada (XXXXXX******XXXX)

Tipos de requerimiento (referencia)

Los tipos de requerimientos que puedes hacer en Azul Webservices son:

  • Sale
  • Refund
  • Hold
  • Post
  • Verify
  • Create token
  • Delete token
  • 3DS Challenge

Consulta esta documentacion para conocer cada uno.

Credits to: https://github.com/mrjeanp for this wiki and postman documentation.

Clone this wiki locally