Servicio de confirmación de pagos externos

Introducción#

La funcionalidad de confirmación de pago de origen externa permite que una transacción de pago creada fuera de Portal Carat sea confirmada dentro de Portal Carat.

Actualmente, esta funcionalidad solo permite la confirmación de las transacciones de pago realizadas en SiTef.

Esta operación se divide en dos pasos:

Creación de una transacción de "Confirmación" que represente la transacción de pago real creada externamente
La confirmación real del pago de esta transacción.

Caso de éxito

El flujo que se muestra abajo ilustra el camino feliz, en el que se inicia la transacción y luego ya se envía la confirmación.

Creación de confirmación de pago de origen externa#

Detalles de la llamada#

Recurso: /v1/transactions
Método HTTP: POST
Formato de solicitud: JSON
Formato de respuesta: JSON
Parámetros de encabezado:

Parámetro	Descripción	Formato	Obligatorio
`merchant_id`	Código de la tienda en Portal Carat. Los códigos de producción y certificación serán diferentes.	< 15 AN	SI
`merchant_key`	Clave de autenticación de la tienda en Portal Carat. Las claves de producción y certificación serán diferentes.	< 80 AN	SI
`Content-Type`	Debe enviarse con el valor `application json`.	= 15 AN	SI

Ejemplo#

Solicitud:

curl --location --request POST 'https://esitef-homologacao.softwareexpress.com.br/e-sitef/api/v1/transactions'
--header 'merchant_id: xxxxxxxxxxxxxxxxxx'
--header 'merchant_key: xxxxxxxxxxxxxxxxxx'
--header 'Content-Type: application/json'
--data-raw '{
    "merchant_usn": "21042858195",
    "order_id": "1621949459257",
    "amount": "300",
    "transaction_type": "confirmation",
    "is_transaction_origin_external": "true"
}'
--verbose

Respuesta:

{
  "code": "0",
  "message": "OK. Transaction successful.",
  "confirmation": {
    "status": "PPC",
    "nit": "1234567890abcdefghijklmnopqrstuvwxyz1234567890abcdefghijklmnopqr",
    "order_id": "1621949459257",
    "merchant_usn": "21042858195",
    "amount": "300"
  }
}

Parámetros de solicitud#

La siguiente tabla muestra los campos para crear una transacción de confirmación de pago de origen externa.

Nombre del parámetro	Descripción	Tamaño	Obligatorio
`amount`	Valor total de la compra (en centavos). Ejemplo: 1,00 = 100 o 1,100,00 = 110000 - envíe el valor sin la coma y el punto	< 12N	Sí
`merchant_usn`	Número secuencial único para cada pedido, creado por la tienda. El NSU se utilizará en todas las comunicaciones con la tienda, con el fin de identificar el pedido. Al tratarse de una posible clave de acceso a la tienda, a pesar de ser opcional para Portal Carat, se recomienda encarecidamente que el campo sea formateado y enviado por la aplicación de la tienda.	< 12 N	NO
`order_id`	Código de pedido que se mostrará al comprador, definido por el comerciante. Es aconsejable que sea diferente para cada pedido para facilitar la rastreabilidad. Si la integración de la Tienda con las redes de adquirencia/enrutamiento (Cielo, Redecard, etc.) es a través de SiTef (TEF), el campo orderId, que tiene un tamaño máximo de 40 caracteres, se reducirá a 12 caracteres, debido a una restricción del SiTef. Esta reducción se realizará manteniendo los caracteres de izquierda a derecha (por ejemplo, si un código de pedido introducido es 12345678901234567890 en Portal Carat, en SiTef será sólo 123456789012).	40 AN	NO

| transaction_type | Constante fija y obligatoria para el tipo de transacción de confirmación de pago de origen externo. Valor = confirmation | < 15 N | SÍ | | is_transaction_origin_external | Constante fija y obligatoria para el tipo de transacción de confirmación de pago de origen externo. Valor = true | < 5 T/F | SÍ |

Parámetros de respuesta#

En caso de éxito, el código de respuesta HTTP será "201". Cualquier otro código debe interpretarse como un error. En la tabla abajo se muestra la descripción de los parámetros de respuesta del servicio de creación de transacciones:

Parámetro	Descripción	Formato
`code`	Código de respuesta Portal Carat. Cualquier código que no sea "0" significa error. Sepa mas.	< 4 N
`message`	Mensaje de respuesta de Portal Carat.	< 500 AN
payment
`status`	Status de la transacción de pago en Portal Carat. [Más información.] (codigos-da-api.md#status-de-transacões-do-e-sitef)	= 3 AN
`nit`	Identificador de transacción de pago en e-SiTef.	= 64 AN
`order_id`	Código de pedido enviado por la tienda al crear la transacción.	< 40 AN
`merchant_usn`	Número secuencial único enviado por la tienda al crear la transacción.	< 12 N
`amount`	Importe de la compra especificado por la tienda (en centavos) al momento de la creación de la transacción.	< 12 N

Efectuar la confirmación del pago de origen externa#

Detalles de la llamada#

Recurso: /v1/payments/{nit}
Método HTTP: PUT
Formato de solicitud: JSON e query string
Formato de respuesta: JSON
Parámetros de encabezado:

Parámetro	Descripción	Formato	Obligatorio
`merchant_id`	Código de la tienda en Portal Carat. Los códigos de producción y certificación serán diferentes.	< 15 AN	SI
`merchant_key`	Clave de autentificación de la tienda en Portal Carat. Las claves de producción y de certificación serán diferentes.	80 AN	SÍ
`Content-Type`	Debe enviarse con el valor `application/json`.	= 15 AN	SÍ

Ejemplo#

Solicitud:

curl --location --request PUT 'https://esitef-homologacao.softwareexpress.com.br/e-sitef/api/v1/payments/bacd62eb62c27f4bf2eae9cef74c93a02e831985eccb6de371628fd272ee5474?confirm=true'
--header 'merchant_id: xxxxxxxxxxxxxx'
--header 'merchant_key: xxxxxxxxxxxxx'
--header 'Content-Type: application/json'
--data-raw '{
    "authorizer_id": "1",
    "installments": "1",
    "installment_type": "4",
    "confirmation_data": "123456789012",
    "acquirer": {
        "routing_id": "5",
        "authorization_number": "212991",
        "identification_number": "11111111111",
        "order_id": "1621949459257",
        "authorizer_date": "21/05/2021",
        "host_usn": "000212991   ",
        "terminal": "HA000006",
        "company_code": "00000000"
    }
}'
--verbose

Respuesta:

{
  "code": "0",
  "message": "OK. Transaction successful.",
  "payment": {
    "authorizer_code": "130",
    "status": "CON",
    "acquirer_id": "5",
    "host_usn": "000212991   "
  }
}

Parámetros de solicitud - query string#

| Parámetro | Descripción | Formato | Obligatorio | | --------- | ---------------------------------------------------------------------------------------------------------------------------------- | -------------- | ----------- | | confirm | Este campo debe enviarse con el valor true si desea confirmar el pago, o false si desea deshacer el pago. | < 5 T / F | SI |

Parámetros de solicitud: JSON#

Parámetro	Descripción	Formato	Obligatorio
`amount`	Monto total de la compra (en centavos). Ejemplo: 1,00 = 100 o 1,100,00 = 110000 - envíe el valor sin la coma y el punto. Si no se informa, asume el valor informado al crear la transacción.	< 12 N	NO
`authorizer_id`	Código de autorización en Portal Carat. [Más información.] (autorizadoras.md)	< 3 N	SI
`installments`	Número de plazos. Envíe "1" para transacciones en efectivo.	< 2 N	NO (\ *)
`installment_type`	TTipo de financiación a plazos: valor 3 = cuotas con intereses de la compañía de tarjetas. valor 4 = cuotas realizadas por la tienda y sin intereses (adopte este valor como norma/defaut para transacciones en efectivo). Valor 6 = pago a plazos con intereses del administrador (IATA). valor 7 = pago a plazos realizado por la tienda y sin intereses (IATA). El pago a plazos IATA solo es utilizado por empresas en el segmento del transporte aéreo.	< 2 N	NO (\ *)
`confirmation_data`	Información de pago devuelta por SiTef cuando se realiza un pago. Este parámetro es esencial para una confirmación exitosa . SiTef lo utiliza para identificar el pago.	< 128 AN	SÍ
acquirer
`routing_id`	Información de enrutamiento utilizada para pagos realizados fuera de Portal Carat. Este parámetro es esencial para una confirmación exitosa . Esta información se utiliza para identificar el enrutamiento en SiTef.	< 5 N	SÍ
`order_id`	Código de pedido enviado por la tienda al crear la transacción.	< 40 AN	NO(*)
`host_usn`	NSU del host / autorizador de la transacción a confirmar.	= 9 N	NO(*)
`authorization_number`	Número de autorización de la operación a ser confirmada.	< 6 N	NO(*)
`authorizer_date`	Fecha efectiva SiTef de pago en formato `DD/MM/AAAA`.	= 10 D	NO(*)
`order_id`	Código de pedido utilizado para el pago iniciado externamente a Portal Carat.	< 40 AN	NO(*)
`identification_number`	CPF o CNPJ utilizados en el pago iniciado externamente a Portal Carat.	< 20 AN	NO(*)
`terminal`	Terminal SiTef que desea utilizar. Si NO se envía, Portal Carat generará una terminal aleatoria.	= 8 AN	NO(*)
`company_code`	Código de la empresa SiTef que desea utilizar. Si no se envía, Portal Carat enviará el código de empresa registrado en la tienda.	= 8 N	NO(*)

Nota: Los campos marcados con NO(*) son opcionales y, en caso de ser informados, no tienen cómo ser constituidos por el Portal Carat, ya que, en la operación de confirmación no son enviados al SiTef. Estos campos, si se introducen, se registrarán en la transacción sólo a efectos de registro.

Parámetros de respuesta#

Si tiene éxito, el código de respuesta HTTP será 200. Cualquier otro código debe interpretarse como un error. En la tabla abajo se muestra la descripción de los parámetros de respuesta del servicio de confirmación de pago:

Parámetro	Descripción	Formato
`code`	Código de respuesta Portal Carat. Cualquier código que no sea `0` significa error. Más información.	< 4 N
`message`	Mensaje de respuesta de Portal Carat.	< 500 AN
payment
`status`	Status de la transacción de pago en Portal Carat. Más información.	= 3 AN
`payment_date`	Fecha efectiva de pago en Portal Carat en el formato `DD/MM/AAAA'T'HH: mm`. Ejemplo: 07/13/2017T16: 03	= 16 D
`host_usn`	Autorizador NSU.	< 15 AN

Home

Introducción#

Creación de confirmación de pago de origen externa#

Detalles de la llamada#

Ejemplo#

Parámetros de solicitud#

Parámetros de respuesta#

Efectuar la confirmación del pago de origen externa#

Detalles de la llamada#

Ejemplo#

Parámetros de solicitud - query string#

Parámetros de solicitud: JSON#

Parámetros de respuesta#