Pago REST

Descripción general#

Portal Carat dispone de dos interfaces de integración con la tienda online, POST/HTML y Web Services (REST), que permiten a la tienda interactuar con lo Portal Carat de forma adecuada, dependiendo del idioma y plataforma de ejecución de la tienda online.

En la interfaz REST, la recogida de datos de la tarjeta y del pago la realizará la Tienda Virtual y Portal Carat solo será responsable de realizar el pago con la entidad financiera.

En esta interfaz, los pagos con tarjeta de crédito, débito o voucher están disponibles.Para los pagos bancarios, como la transferencia bancaria o el boleto, utilice la interfaz POST/HTML.

Y para saber más sobre estas nomenclaturas (Bin, Software Express, Carat, e-Sitef) Leer más

Comunicación#

Para realizar una transacción de Web Service, toda la comunicación se realizará a través de HTTPS/SSL. Es importante que el servidor comercial admita al menos una codificación de 128 bits. El servidor de la tienda debe realizar llamadas a direcciones específicas para transacciones REST.

Cada servicio debe ser llamado utilizando URL base concatenada del recurso deseado (ver el capítulo referente al servicio que se va a consumir). El método HTTP (GET, POST o PUT) indica la acción esperada en el recurso elegido. A bajo se muestran las URL base de Portal Carat:

URL base de producción:

https://esitef.softwareexpress.com.br/e-sitef/api

URL base de aprobación:

https://esitef-homologacao.softwareexpress.com.br/e-sitef/api

Todas las llamadas realizadas a los servicios serán respondidas sincrónicamente .

Atención:
Nunca use la IP en lugar del dominio esitef.softwareexpress.com.br. La IP puede cambiar en cualquier momento y sin previo aviso, por lo que es importante utilizar el dominio para acceder al Portal Carat.

Importante:
Además de los parámetros de devolución del servicio descritos en esta especificación, Portal Carat puede devolver otros parámetros sin previo aviso.
Es importante que la aplicación esté preparada para recibir los parámetros desconocidos además de los parámetros ya especificados y simplemente ignorarlos.

Flujo#

El flujo de pago será iniciado por la aplicación de la tienda electrónica después de que el cliente finalice la compra y complete su información de pago.

Existen dos tipos de flujo de pago: con confirmación automática, donde Portal Carat se encarga de confirmar el pago con las Redes Adquirientes y con confirmación tardía, donde la aplicación se encarga de confirmar el pago, consumiendo el servicio de confirmación.

La confirmación tardía se utiliza generalmente cuando la aplicación de la tienda online permite el pago con más de una tarjeta o si se realiza alguna validación antes de realizar el pago.

Pago con confirmación automática#

Descripción del flujo:

El comerciante crea una transacción en API, pasando información como el código de la tienda, el número de cuotas y el código de pedido y obtiene un NIT (Número de identificación de la transacción) en respuesta.
La tienda virtual luego procede a consumir el servicio de procesamiento de pagos, pasando el NIT y los datos de la tarjeta del comprador. Si tiene éxito, la transacción de pago cambiará su estado a CON (confirmado).

Ejemplo

Para usar este ejemplo, no olvide definir la variable {{url}} con el valor
esitef-homologacao.softwareexpress.com.br

Pedido:

curl --location 'https://{{url}}/e-sitef/api/v2/payments/' --header 'Content-Type: application/json' --header 'merchant_id: xxxxxxxxx' --header 'merchant_key: xxxxxxxxxxxxxx' --data '{
    "merchant_usn": "12050620649",
   "order_id":"1686591679260",
    "installments": "1",
    "installment_type": "4",
    "authorizer_id": "2",
    "amount": "1100",
    "card": {
        "expiry_date": "1222",
        "security_code": "123",
        "number": "5555555555555555",
        "cryptogram": "ALRzlt6NKQtPAAZAkOuIAAADFA==",
        "wallet_type": "network_token"
    }
}'

Respuesta: (tenga en cuenta el estado de la transacción, que es CON de Confirmado)

{
    "code": "0",
    "message": "OK. Transaction successful.",
    "payment": {
        "authorizer_code": "000",
        "authorizer_message": "APROVADA",
        "status": "CON",
        "nit": "dc8a370d394e3868de756b53b912a3b41cffdf28e26bff405ddb20737bce5e06",
        "order_id": "1686591679260",
        "customer_receipt": "==== customer receipt ====",
        "merchant_receipt": "==== merchant receipt ====",
        "authorizer_id": "2",
        "acquirer_id": "229",
        "acquirer_name": "Bin",
        "authorizer_date": "12/06/2023T14:41",
        "authorization_number": "000026",
        "merchant_usn": "12050620649",
        "esitef_usn": "230612015722270",
        "sitef_usn": "000026",
        "host_usn": "006000026   ",
        "amount": "1100",
        "payment_type": "C",
        "issuer": "2",
        "authorizer_merchant_id": "000000000000000",
        "terminal_id": "ES000001",
        "payment_date": "12/06/2023T14:41",
        "recurrency_tid": "999988887777666"
    }
}

Pago con confirmación tardía#

Descripción de flujo:

Asi como en el flujo de pago con confirmación automática, el comerciante crea una transacción en API, pasando los detalles del pago. Además, debe enviar el parámetro postpone_confirmation con valor true.
La tienda virtual luego procede a consumir el servicio de procesamiento de pago, pasando el NIT y los datos de la tarjeta del comprador. Si tiene éxito, la transacción de pago cambiará su estado a PPC (pago pendiente de confirmación).
En conclusión, la tienda virtual llama al servicio de confirmación de pago, volviendo a pasar el NIT y el parámetro confirm con un valor de true, dando como resultado una transacción con estado CON (confirmado). También existe la posibilidad de que el comerciante deshaga la transacción en lugar de confirmar. Para esto, el parámetro confirm debe enviarse con un valor de false, lo que dará como resultado una transacción con status PPN (deshecho).