Desarrolladores

# Integración sin Pantalla (SOAP)

# Preámbulo

Esta guía describe los métodos y parámetros disponibles en la plataforma Ztrans utilizada para procesar transacciones de comercio electrónico con el protocolo de comunicación web services para comercios afiliados a Cardnet.

# Métodos Disponibles

Los métodos disponibles utilizando WSDL serían los siguientes:

  • createIdempotencyKey: Método utilizado para obtener el idempotencykey, este valor deberá solicitarse antes de cada requerimiento de pago, o sea, primero se debe obtener el idempotencykey y luego agregarlo al mensaje de solicitud de pago (processSale).

  • processSale: Método utilizado para enviar requerimientos de venta con tarjeta, se debe tener en cuenta que en cada solicitud deberá enviarse el valor de idempotencykey previamente generado. Una vez que la transacción sea completada debería recibir el código de respuesta 00 y la descripción “Transaction Approved”.

  • processVoid: Método utilizado para anular un pago previamente autorizado. Para consumir este método deberá enviar información obtenida de la respuesta del pago. Las anulaciones solamente podrían enviarse antes de realizar el proceso de cierre. A partir de la versión 1.8 se podrá anular autorizaciones de Hold o Check In

  • processCheckIn: Método utilizado para realizar un check in y/o cargo autorizado al disponible de un TH. Para poder liquidar esta transacción deberá enviar una confirmación o check out con los datos de la transacción original.

  • processCheckout: Método utilizado para realizar un check out de un cargo autorizado anteriormente al disponible de un TH. Con esta confirmación se podrá liquidar la transacción original. Este podrá ser aplicado con un monto igual o menor a la transacción original.

# createIdempotencyKey

# Parámetros de Solicitud

# createIdempotencyKey

  • Formato: string
  • Descripción: Valor identificador de transacción

# Ejemplo de Solicitud

<soapenv:Envelope
  xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
  xmlns:api="http://api.services.cardnet.com.do">
    <soapenv:Header/>
    <soapenv:Body>
        <api:createIdempotencyKey/>
    </soapenv:Body>
</soapenv:Envelope>

# Parámetros de Respuesta

# idempotency-key

  • Formato: string
  • Descripción: Valor identificador de transacción

# Ejemplo de Respuesta

<soap:Envelope
  xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
    <soap:Body>
        <ns2:createIdempotencyKeyResponse
          xmlns:ns2="http://api.services.cardnet.com.do">
            <return>ikey:e6efd5423b694afabfc5818cb6e2a592</return>
        </ns2:createIdempotencyKeyResponse>
    </soap:Body>
</soap:Envelope>

# processSale

# Parámetros de Solicitud

# Token

  • Formato: string
  • Descripción: Valor generado por la aplicación del cliente.

# idempotency-key

  • Formato: string
  • Descripción: Valor identificador de transacción.

# merchant-id

  • Formato: string
  • Descripción: Número de afiliado del comercio.

# terminal-id

  • Formato: string
  • Descripción: Número de terminal id del comercio.

# card-number

  • Formato: string
  • Descripción: Número de tarjeta utilizada para realizar el pago.

# Environment

  • Formato: string
  • Descripción: Valor utilizado para identificar el tipo de transacción: Ecommerce, MOTO, Atended, MOTO_Recurring, QuasiCashMT.

# pstr43

  • Formato: string
  • Longitud máxima: 25 caracteres.
  • Descripción: Parámetro opcional para autenticar la transacción.

# Pstr63

  • Formato: string
  • Longitud máxima: 3 caracteres.
  • Descripción: Parámetro Opcional para las transacciones en cuotas y Puntos (C06,P00).

# expiration-date

  • Formato: string
  • Descripción: Fecha de expiración de la tarjeta MM/YY.

# Cvv

  • Formato: string
  • Descripción: Número de validación de tarjeta.

# Amount

  • Formato: decimal
  • Descripción: Monto de la transacción.

# Tip

  • Formato: decimal
  • Descripción: Monto de propina.

# Tax

  • Formato: decimal
  • Descripción: Monto de impuesto pagado.

# Currency

  • Formato: string
  • Descripción: Código de moneda.

# invoice-number

  • Formato: string
  • Descripción: Número de referencia del sistema.

# client-ip

  • Formato: string
  • Descripción: Dirección Ip de la aplicación cliente.

# reference-number

  • Formato: string
  • Descripción: Número de referencia del pago.

# Ejemplo de Solicitud

<soapenv:Envelope
  xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
  xmlns:api="http://api.services.cardnet.com.do">
    <soapenv:Header/>
    <soapenv:Body>
        <api:processSale>
            <arg0 token="454500350001" idempotency-key=" ikey:06ded1a51b214c3eae5a1b4b73957721">
                <merchant-id>349000001</merchant-id>
                <terminal-id>454500350001</terminal-id>
                <environment>Ecommerce</environment>
                <card-number>5400********9571</card-number>
                <expiration-date>12/17</expiration-date>
                <cvv>747</cvv>
                <amount>300.00</amount>
                <tip>0.00</tip>
                <tax>0.00</tax>
                <currency>214</currency>
                <invoice-number>000003</invoice-number>
                <client-ip>10.x.x.x</client-ip>
                <reference-number>000003</reference-number>
            </arg0>
        </api:processSale>
    </soapenv:Body>
</soapenv:Envelope>

# Parámetros de Respuesta

# idempotency-key

  • Formato: string
  • Descripción: Valor identificador de transacción.

# response-code

  • Formato: string
  • Descripción: Código de respuesta del autorizador de tarjeta.

# internal-response-code

  • Formato: string
  • Descripción: Código de respuesta interno de la plataforma.

# response-code-desc

  • Formato: string
  • Descripción: Descripción del código de respuesta.

# response-code-source

  • Formato: string
  • Descripción: Origen de la repuesta, gw= respuesta de la plataforma. Icache= Respuesta generada de una transacción con el mismo idempotency key.

# approval-code

  • Formato: string
  • Descripción: Número de autorización del banco emisor.

# pnRef

  • Formato: string
  • Descripción: Número de referencia de la plataforma.

# Ejemplo de Respuesta

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
    <soap:Body>
        <ns2:processSaleResponse xmlns:ns2="http://api.services.cardnet.com.do">
            <return idempotency-key="ikey:06ded1a51b214c3eae5a1b4b73957721">
                <response-code>00</response-code>
                <internal-response-code>0000</internal-response-code>
                <response-code-desc>Transaction Approved</response-code-desc>
                <response-code-source>gw</response-code-source>
                <approval-code>006458</approval-code>
                <pnRef>txn-df93d31bee3e4ec88b6890914ca588ab</pnRef>
            </return>
        </ns2:processSaleResponse>
    </soap:Body>
</soap:Envelope>

# processVoid

# Parámetros de Solicitud

# Token

  • Formato: string
  • Descripción: Valor generado por la aplicación del cliente.

# idempotency-key

  • Formato: string
  • Descripción: Valor identificador de transacción, deberá agregarse el valor del requerimiento original.

# merchant-id

  • Formato: string
  • Descripción: Número de afiliado del comercio.

# terminal-id

  • Formato: string
  • Descripción: Número de terminal id del comercio.

# Enviroment

  • Formato: string
  • Descripción: Valor utilizado para identificar el tipo de transacción: Ecommerce, MOTO, Atended.

# Ejemplo de Solicitud

<soapenv:Envelope
  xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
  xmlns:api="http://api.services.cardnet.com.do">
    <soapenv:Header/>
    <soapenv:Body>
        <api:processVoid>
            <!--Optional:-->
            <arg0 token="454500350001" idempotency-key="ikey:e6efd5423b694afabfc5818cb6e2a592">
                <!--Optional:-->
                <merchant-id>349000001</merchant-id>
                <!--Optional:-->
                <terminal-id>454500350001</terminal-id>
                <!--Optional:-->
                <amount>300.00</amount>
                <!--Optional:-->
                <currency>214</currency>
                <!--Optional:-->
                <pnRef>txn-df93d31bee3e4ec88b6890914ca588ab</pnRef>
            </arg0>
        </api:processVoid>
    </soapenv:Body>
</soapenv:Envelope>

# Parámetros de Respuesta

# idempotency-key

  • Formato: string
  • Descripción: Valor identificador de transacción.

# response-code

  • Formato: string
  • Descripción: Código de respuesta del autorizador de tarjeta.

# internal-response-code

  • Formato: string
  • Descripción: Código de respuesta interno de la plataforma.

# response-code-desc

  • Formato: string
  • Descripción: Descripción del código de respuesta.

# response-code-source

  • Formato: string
  • Descripción: Origen de la repuesta, gw= respuesta de la plataforma. Icache= Respuesta generada de una transacción con el mismo idempotency key.

# approval-code

  • Formato: string
  • Descripción: Número de autorización generado por el banco emisor.

# PnRef

  • Formato: string
  • Descripción: Número de referencia de la plataforma.

# Ejemplo de Respuesta

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
    <soap:Body>
        <ns2:processVoidResponse xmlns:ns2="http://api.services.cardnet.com.do">
            <return idempotency-key="ikey:e6efd5423b694afabfc5818cb6e2a592">
                <response-code>00</response-code>
                <internal-response-code>0000</internal-response-code>
                <response-code-desc>Transaction Approved</response-code-desc>
                <response-code-source>gw</response-code-source>
                <approval-code>436258</approval-code>
                <pnRef>txn-f9708ab42e054d759ab097cc0c9be0e7</pnRef>
            </return>
        </ns2:processVoidResponse>
    </soap:Body>
</soap:Envelope>

# processCheckIn

# Parámetros de Solicitud

# Token

  • Formato: string
  • Descripción: Valor generado por la aplicación del cliente.

# idempotency-key

  • Formato: string
  • Descripción: Valor identificador de transacción.

# merchant-id

  • Formato: string
  • Descripción: Número de afiliado del comercio.

# terminal-id

  • Formato: string
  • Descripción: Número de terminal id del comercio.

# card-number

  • Formato: string
  • Descripción: Número de tarjeta utilizada para realizar el pago.

# Environment

  • Formato: string
  • Descripción: Valor utilizado para identificar el tipo de transacción: Ecommerce, MOTO, Atended, MOTO_Recurring. QuasiCashMT.

# pstr43

  • Formato: string
  • Longitud máxima: 25
  • Descripción: Parámetro opcional para autenticar la transacción.

# expiration-date

  • Formato: string
  • Descripción: Fecha de expiración de la tarjeta MM/YY.

# Cvv

  • Formato: string
  • Descripción: Número de validación de tarjeta.

# Amount

  • Formato: decimal
  • Descripción: Monto de la transacción.

# Tip

  • Formato: decimal
  • Descripción: Monto de propinas.

# Tax

  • Formato: decimal
  • Descripción: Monto de impuesto pagado.

# Currency

  • Formato: string
  • Descripción: Código de moneda.

# invoice-number

  • Formato: string
  • Descripción: Número de referencia del sistema.

# client-ip

  • Formato: string
  • Descripción: Dirección Ip de la aplicación cliente.

# reference-number

  • Formato: string
  • Descripción: Número de referencia del pago.

# Ejemplo de Solicitud

<soapenv:Envelope
  xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
  xmlns:api="http://api.services.cardnet.com.do">
    <soapenv:Header/>
    <soapenv:Body>
        <api:processCheckIn>
            <arg0 token="3abc4d785afa42b19eeda8e1c470ed4d" idempotency-key="3abc4d785afa42b19eeda8e1c470ed4d">
                <merchant-id>349000000</merchant-id>
                <terminal-id>58585858</terminal-id>
                <environment>ECOMMERCE</environment>
                <card-number>493788*4224</card-number>
                <expiration-date>05/09</expiration-date>
                <cvv>123</cvv>
                <amount>350</amount>
                <tip></tip>
                <tax></tax>
                <currency>214</currency>
                <invoice-number>12345</invoice-number>
                <client-ip>192.168.10.2</client-ip>
                <reference-number>12345</reference-number>
                <pstr43></pstr43>
            </arg0>
        </api:processCheckIn>
    </soapenv:Body>
</soapenv:Envelope>

# Parámetros de Respuesta

# idempotency-key

  • Formato: string
  • Descripción: Valor identificador de transacción.

# response-code

  • Formato: string
  • Descripción: Código de respuesta del autorizador de tarjeta.

# internal-response-code

  • Formato: string
  • Descripción: Código de respuesta interno de la plataforma.

# response-code-desc

  • Formato: string
  • Descripción: Descripción del código de respuesta.

# response-code-source

  • Formato: string
  • Descripción: Origen de la repuesta, gw= respuesta de la plataforma. Icache= Respuesta generada de una transacción con el mismo idempotency key.

# approval-code

  • Formato: string
  • Descripción: Número de autorización del banco emisor.

# TrToken

  • Formato: string
  • Descripción: Token de la respuesta de la transacción original realizada, utilizado para transacción Check-out.

# Ejemplo de Respuesta

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
    <soap:Body>
        <ns2:processCheckInResponse xmlns:ns2="http://api.services.cardnet.com.do">
            <return idempotency-key="3abc4d785afa42b19eeda8e1c470ed4d">
                <response-code>00</response-code>
                <internal-response-code>0000</internal-response-code>
                <response-code-desc>Transaction Approved</response-code-desc>
                <response-code-source>gw</response-code-source>
                <approval-code>030303</approval-code>
                <txToken>txn-7839e7cee09f47668a77b72554f44b02</txToken>
            </return>
        </ns2:processCheckInResponse>
    </soap:Body>
</soap:Envelope>

# processCheckout

# Parámetros de Solicitud

# token

  • Formato: string
  • Descripción: Valor generado por la aplicación del cliente

# idempotency-key

  • Formato: string
  • Descripción: Valor identificador de transacción, deberá agregarse el valor del requerimiento original.

# merchant-id

  • Formato: string
  • Descripción: Numero de afiliado del comercio

# terminal-id

  • Formato: string
  • Descripción: Numero de terminal id del comercio

# enviroment

  • Formato: string
  • Descripción: Valor utilizado para identificar el tipo de transacción: Ecommerce, MOTO, Atended

# amount

  • Formato: decimal
  • Descripción: Monto de la transacción a confirmar.ya sea igual o menor a la transacción original

# client-ip

  • Formato: string
  • Descripción: IP de origen de la solicitud de la confirmación

# reference-number

  • Formato: string
  • Descripción: Referencia de la transacción definida por el cliente.

# approval-code

  • Formato: string
  • Descripción: Numero de aprobación del Check in original de la transacción

# txToken

  • Formato: string
  • Descripción: Token de la respuesta de la transacción original realizada

# Ejemplo de Solicitud

<soapenv:Envelope
  xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
  xmlns:api="http://api.services.cardnet.com.do">
    <soapenv:Header/>
    <soapenv:Body>
        <api:processCheckout>
            <arg0 token="eda518c9559c4c588f7c1cbd41a05917" idempotency-key="eda518c9559c4c588f7c1cbd41a05917">
                <merchant-id>349000000</merchant-id>
                <terminal-id>58585858</terminal-id>
                <environment>ECommerce</environment>
                <amount>350.00</amount>
                <itbis>50.00</itbis>
                <client-ip>192.168.10.2</client-ip>
                <reference-number>12345</reference-number>
                <approval-code>030303</approval-code>
                <txToken>txn-7839e7cee09f47668a77b72554f44b02</txToken>
            </arg0>
        </api:processCheckout>
    </soapenv:Body>
</soapenv:Envelope>

# Parámetros de Respuesta

# idempotency-key

  • Formato: string
  • Descripción: Valor identificador de transacción

# response-code

  • Formato: string
  • Descripción: Código de respuesta del autorizador de tarjeta

# internal-response-code

  • Formato: string
  • Descripción: Código de respuesta interno de la plataforma

# response-code-desc

  • Formato: string
  • Descripción: Descripción del código de respuesta

# response-code-source

  • Formato: string
  • Descripción: Origen de la repuesta, gw= respuesta de la plataforma. Icache= Respuesta generada de una transaccion con el mismo idempotency key.

# approval-code

  • Formato: string
  • Descripción: Número de autorización generado por el banco emisor, referente a la transacción original.

# txToken

  • Formato: string
  • Descripción: Número de referencia de la plataforma

# Ejemplo de Respuesta

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
    <soap:Body>
        <ns2:processCheckoutResponse xmlns:ns2="http://api.services.cardnet.com.do">
            <return idempotency-key="3abc4d785afa42b19eeda8e1c470ed4d">
                <response-code>00</response-code>
                <internal-response-code>0000</internal-response-code>
                <response-code-desc>Transaction Approved</response-code-desc>
                <response-code-source>gw</response-code-source>
                <approval-code>030303</approval-code>
                <txToken>txn-7839e7cee09f47668a77b72554f44b02</txToken>
            </return>
        </ns2:processCheckoutResponse>
    </soap:Body>
</soap:Envelope>