Facilitador de Pagos
Visión general#
Este artículo presentará funciones para enrutar transacciones en el Facilitador de pagos a través de adquisiciones procesadas por Fiserv.
Atención: Para operar como Facilitador de Pagos, necesitará tener un ID de PFAC con las marcas, firmar un contrato con el adquirente y solicitar acceso al entorno específico para realizar pruebas.
Los establecimientos que operan como Facilitadores de Pago intermedian a otros establecimientos (subcomerciantes) para aceptar pagos electrónicos en el adquirente. Para operar en este modo será necesario solicitar la configuración en el registrar y transmitir información específica sobre las operaciones de sus subcomerciantes según instrucciones.
Pago#
- Recurso:
/e-sitef/api/v2/payments/ - Método HTTP:
POST - Formato da solicitud:
JSON - Formato da respuesta:
JSON - Parámetros de encabezado:
| Parámetro | Descripción | Formato | Obligatorio |
|---|---|---|---|
merchant_id | Código de tienda en el Portal Carat. Los códigos de producción y certificación serán diferentes. | < 15 AN | SI |
merchant_key | Clave de autenticación para la tienda de Pagos Online. 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#
Para usar este ejemplo, no olvides definir la variable {{url}} con el valor
esitef-homologacao.softwareexpress.com.br
Pedido:
Parámetros del pedido
La siguiente tabla describe los parámetros de solicitud del servicio de creación de transacciones:
Aqui está a tabela traduzida para o espanhol argentino:
| Parámetro | Descripción | Formato | Requerido |
|---|---|---|---|
merchant_usn | Número secuencial único para cada pedido, creado por la tienda. El NSU se utilizará en toda la comunicación con la tienda, para identificar el pedido. Aunque es una posible clave de acceso del lado de la tienda, y es opcional para 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 del pedido que se mostrará al comprador, definido por el comerciante. Se aconseja que sea diferente para cada pedido para facilitar el rastreo. Si la integración de la Tienda con las redes adquirentes (Cielo, Redecard, etc.) es con Carat y SiTef, el campo orderId, que tiene un tamaño máximo de 40 caracteres, se reducirá a 12 caracteres debido a una restricción de SiTef. Esta reducción se realizará manteniendo los caracteres de izquierda a derecha (por ejemplo, si se inserta un código de pedido de 12345678901234567890 en Carat, en SiTef será solo 123456789012). | < 40 AN | NO |
installments | Número de cuotas. Enviar '1' para transacciones al contado. | < 2 N | SÍ |
installment_type | Tipo de financiación de la cuota: valor 3 = financiación con intereses de la administradora de la tarjeta. valor 4 = financiación realizada por la tienda sin intereses (adoptar este valor como predeterminado para transacciones al contado). Valor 6 = financiación con intereses de la administradora (IATA). valor 7 = financiación realizada por la tienda sin intereses (IATA). La financiación IATA es utilizada únicamente por empresas del sector de transporte aéreo. | < 2 N | SÍ |
authorizer_id | Código de la autorizadora en Carat. Más información. | < 3 N | NO |
amount | Valor total de la compra (en centavos). Ejemplo: 1,00 = 100 o 1.100,00 = 110000 – enviar el valor sin comas ni puntos. | < 12 N | SÍ |
soft_descriptor | Texto adicional que se mostrará junto al nombre del establecimiento en el estado de cuenta de la tarjeta de crédito del comprador. Más información | < 25 AN | SÍ |
| card | Datos de la tarjeta. | ||
expiry_date | Fecha de vencimiento de la tarjeta en formato MMAA. | < = 4 N | COND. |
security_code | Código de seguridad. | < < 5 N | COND. |
number | Número de la tarjeta del comprador (PAN). | < 5 T/F | NO |
holder | Nombre del comprador | < 40 AN | SÍ |
| additional_data | Elemento para el envío de datos adicionales. | ||
mcc | Código de comercio (Merchant Category Code) | < = 4 N | SÍ |
| subacquirer_merchant | Datos del comerciante subadquirente. | ||
id | Código de establecimiento del subseller. | = 15 N | SÍ |
address | Dirección del Subseller. | < 120 AN | SÍ |
city | Ciudad. | < 20 AN | SÍ |
state | Provincia. | < 30 AN | SÍ |
country | País según código numérico de la ISO 3166. | < 3 N | SÍ |
zip_code | Código postal. | < 8 N | SÍ |
identification_number | Número de identificació del subseller | < 18 N | SÍ |
payment_facilitator_id | ID del facilitador de pago. (Si no llega a 11 caracteres, añade ceros a la izquierda) | = 11 N | SÍ |
payment_facilitator_url | URL del facilitador de pago. | < 76 AN | SÍ |
phone_number | Número de teléfono. | < 15 N | SÍ |
Respuesta:
Parámetros de respuesta
Si tiene éxito, el código de respuesta HTTP será "201". Cualquier otro código debe interpretarse como un error. La siguiente tabla describe los parámetros de respuesta del servicio de creación de transacciones:
| Parámetro | Descripción | Formato |
|---|---|---|
code | Código de respuesta del Carat. Cualquier código diferente de 0 significa falla. Más información. | < 4 N |
message | Mensaje de respuesta del Carat. | < 500 AN |
| payment | ||
authorizer_code | Código de respuesta del autorizador. | < 10 AN |
authorizer_message | Mensaje de respuesta del autorizador. | < 500 AN |
status | Estado de la transacción de pago en el Carat. Más información. | = 3 AN |
nit | Identificador de la transacción de pago en el Carat. | = 64 AN |
order_id | Código de pedido enviado por el comercio al crear la transacción. | < 40 AN |
customer_receipt | Recibo (vía cliente). | < 4000 AN |
merchant_receipt | Recibo (vía establecimiento). | < 4000 AN |
authorizer_id | Código del autorizador utilizado en la transacción. | < 4 N |
acquirer_id | Código del adquirente utilizado en la transacción. | < 4 N |
acquirer_name | Nombre del adquirente utilizado en la transacción. | < 100 AN |
authorizer_date | Fecha de efectivización del pago devuelta por el autorizador en el formato DD/MM/AAAA'T'HH:mm. Ejemplo: 13/07/2017T16:03 | = 16 D |
authorization_number | Número de autorización. | < 6 AN |
merchant_usn | Número secuencial único enviado por el comercio al crear la transacción. | < 12 N |
esitef_usn | Número secuencial único de la transacción de pago en el Carat. | = 15 N |
sitef_usn | Número secuencial único de la transacción de pago en el SiTef. | = 6 N |
host_usn | NSU del autorizador. Aplicable a la efectivización de pagos PIX. | < 15 AN |
amount | Valor de la compra especificado por el comercio (en centavos) al crear la transacción. | < 12 N |
payment_type | Tipo de pago del autorizador elegido: B = boleto, C = crédito, D = débito, P = tarjeta de crédito Private Label, T = transferencia bancaria, G = tarjeta de regalo, O = otros medios de pago, W = Boleto NR vía Web Service | = 1 AN |
terminal_id | Código del terminal utilizado en la transacción | < 8 N |
payment_date | Fecha de efectivización del pago en el Carat en el formato DD/MM/AAAA'T'HH:mm. Ejemplo: 13/07/2017T16:03 | = 16 D |
Autorización previa#
- Recurso:
/e-sitef/api/v2/preauthorizations/ - Método HTTP:
POST - Formato da solicitud:
JSON - Formato da respuesta:
JSON - Parámetros de encabezado:
| Parámetro | Descripción | Formato | Obligatorio |
|---|---|---|---|
merchant_id | Código de tienda en el Portal Carat. Los códigos de producción y certificación serán diferentes. | < 15 AN | SI |
merchant_key | Clave de autenticación para la tienda de Pagos Online. 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#
Para usar este ejemplo, no olvides definir la variable {{url}} con el valor
esitef-homologacao.softwareexpress.com.br
Pedido:
Parámetros del pedido
| Parámetro | Descripción | Formato | Requerido |
|---|---|---|---|
merchant_usn | Número de secuencia único asignado a cada pedido por la tienda. Este número se utilizará en toda la comunicación con la tienda para identificar de forma única cada pedido. Aunque es opcional para Carat, se recomienda fuertemente que la tienda lo incluya en el formato indicado. | < 12 N | NO |
order_id | Código del pedido que se muestra al comprador y que es asignado por el comerciante. Se recomienda que este código sea único para cada pedido para facilitar su seguimiento. Si la integración de la Tienda con las redes adquirentes (Cielo, Redecard, etc) es con Carat y SiTef, el campo orderId que tiene un tamaño máximo de 40 caracteres, se reducirá a 12 caracteres debido a una restricción de SiTef. Esta reducción se hará manteniendo los caracteres de izquierda a derecha (ej.: si un código de pedido inserido es 12345678901234567890 en Carat, en SiTef será sólo 123456789012). | < 40 AN | NO |
installments | Cantidad de cuotas en las que se dividirá el pago. Para pagos al contado, indicar '1'. | < 2 N | SÍ |
installment_type | Tipo de financiamiento de las cuotas: valor 3 = financiación con interés de la entidad emisora de la tarjeta. valor 4 = financiación realizada por la tienda sin interés (usar este valor por defecto para pagos al contado). Valor 6 = financiación con interés de la entidad emisora (IATA). valor 7 = financiación realizada por la tienda sin interés (IATA). La financiación IATA es utilizada solo por empresas del sector de transporte aéreo. | < 2 N | SÍ |
authorizer_id | Código de la entidad autorizadora en Carat. Saiba mais. | < 3 N | NO |
amount | Valor total de la compra (en centavos). Ejemplo: 1,00 = 100 o 1.100,00 = 110000 – enviar el valor sin la coma y punto. | < 12 N | SÍ |
soft_descriptor | Texto adicional que se mostrará junto al nombre del establecimiento en el resumen de tarjeta del comprador. Saiba más | < 25 AN | NO |
| card | Datos de la tarjeta. | ||
expiry_date | Fecha de vencimiento de la tarjeta en formato MM/AA. | < = 4 N | COND. |
security_code | Código de seguridad. | < < 5 N | COND. |
number | Número de la tarjeta del comprador (PAN). | < 5 T/F | NO |
holder | Nombre comercial (Merchant Name) | < 40 AN | SÍ |
| additional_data | Elemento para enviar datos adicionales. | ||
mcc | Código de comercio (Merchant Category Code) | < = 4 N | SÍ |
| subacquirer_merchant | Datos del subadquirente | ||
id | Código del subseller | = 15 N | SÍ |
address | Dirección del subseller | < 120 AN | SÍ |
city | Ciudad | < 20 AN | SÍ |
state | Provincia | < 30 AN | SÍ |
country | País según código numérico de la ISO 3166 | < 3 N | SÍ |
zip_code | Código postal | < 8 N | SÍ |
identification_number | Número de identificación del subseller | < 18 N | SÍ |
payment_facilitator_id | Id del facilitador de pago | < 11 N | SÍ |
payment_facilitator_url | Url del facilitador de pago | < 76 AN | SÍ |
phone_number | Número de teléfono | < 15 N | SÍ |
Respuesta:
Parámetros de respuesta
| Parámetro | Descripción | Formato |
|---|---|---|
code | Código de respuesta de Carat. Cualquier código distinto de 0 indica un error. Más información: | < 4 N |
message | Mensaje de respuesta de Carat. | < 500 AN |
| pre_authorization | ||
authorizer_code | Código de respuesta del autorizador. | < 10 AN |
status | Estado de la transacción de pago en Carat. Más información: | = 3 AN |
nit | Identificador de la transacción de pago en Carat. | = 64 AN |
order_id | Código de pedido enviado por la tienda al crear la transacción. | < 40 AN |
customer_receipt | Comprobante (para el cliente). | < 4000 AN |
merchant_receipt | Comprobante (para el establecimiento). | < 4000 AN |
authorizer_id | Número de secuencia único enviado por la tienda al crear la transacción. | < 12 N |
acquirer_id | Código del adquirente utilizado en la transacción. | < 4 N |
acquirer_name | Nombre del adquirente utilizado en la transacción. | < 100 AN |
authorizer_date | Fecha de efectivación del pago devuelta por el autorizador en formato DD/MM/AAAA'T'HH:mm. Ejemplo: 13/07/2017T16:03 | = 16 D |
authorization_number | Número de autorización. | < 6 AN |
merchant_usn | Número de secuencia único enviado por la tienda al crear la transacción. | < 12 N |
esitef_usn | Número de secuencia único de la transacción de pago en Carat. | = 15 N |
sitef_usn | Número de secuencia único de la transacción de pago en SiTef. | = 6 N |
host_usn | NSU de la autorizadora. Observación para la concreción de pagos PIX. | < 15 AN |
amount | Valor de la compra especificado por la tienda (en centavos) al crear la transacción. | < 12 N |
payment_type | Tipo de pago de la autorizadora seleccionada: B = boleto, C = crédito, D = débito, P = tarjeta de crédito Private Label puro, T = transferencia bancaria, G = tarjeta de regalo, O = otros medios de pago, W = Boleto NR vía Web Service | = 1 AN |
terminal_id | Código del terminal utilizado en la transacción | < 8 N |
payment_date | Fecha de efectivación del pago en Carat en formato DD/MM/AAAA'T'HH:mm. Ejemplo: 13/07/2017T16:03 | = 16 D |
Atrapar#
- Recurso:
/e-sitef/api/v1/preauthorizations/capture/{{nit}} - Método HTTP:
POST - Formato da solicitud:
JSON - Formato da respuesta:
JSON - Parámetros de encabezado:
| Parámetro | Descripción | Formato | Obligatorio |
|---|---|---|---|
merchant_id | Código de tienda en el Portal Carat. Los códigos de producción y certificación serán diferentes. | < 15 AN | SI |
merchant_key | Clave de autenticación para la tienda de Pagos Online. 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#
Para usar este ejemplo, no olvides definir la variable {{url}} con el valor
esitef-homologacao.softwareexpress.com.br
Pedido:
Parámetros del pedido
| Parâmetro | Descripción | Formato | Requerido |
|---|---|---|---|
amount | Valor total de la compra (en centavos). Ejemplo: 1,00 = 100 o 1.100,00 = 110000 – enviar el valor sin la coma y punto. | < 12 N | SÍ |
installments | Cantidad de cuotas en las que se dividirá el pago. Para pagos al contado, indicar '1'. | < 2 N | SÍ |
installment_type | Tipo de financiamiento de las cuotas: valor 3 = financiación con interés de la entidad emisora de la tarjeta. valor 4 = financiación realizada por la tienda sin interés (usar este valor por defecto para pagos al contado). Valor 6 = financiación con interés de la entidad emisora (IATA). valor 7 = financiación realizada por la tienda sin interés (IATA). La financiación IATA es utilizada solo por empresas del sector de transporte aéreo. | < 2 N | SÍ |
mcc | Código de comercio (Merchant Category Code) | < = 4 N | SÍ |
soft_descriptor | Texto adicional que se mostrará junto al nombre del establecimiento en el resumen de tarjeta del comprador. Saiba mais | < 25 AN | NO |
| card | Datos de la tarjeta. | ||
expiry_date | Fecha de vencimiento de la tarjeta en formato MM/AA. | < = 4 N | COND. |
security_code | Código de seguridad. | < < 5 N | COND. |
number | Número de la tarjeta del comprador (PAN). | < 5 T/F | NO |
holder | Nombre comercial (Merchant Name) | < 40 AN | SÍ |
| subacquirer_merchant | Datos del subadquirente | ||
id | Id del subseller | = 15 N | SÍ |
address | Dirección del subseller | < 120 AN | SÍ |
city | Ciudad | < 20 AN | SÍ |
state | Provincia | < 30 AN | SÍ |
country | País según código numérico de la ISO 3166 | < 3 N | SÍ |
zip_code | Código postal | < 8 N | SÍ |
identification_number | Número de identificación del subseller | < 18 N | SÍ |
payment_facilitator_id | Id del facilitador de pago (Si no llega a 11 caracteres, añade ceros a la izquierda) | = 11 N | SÍ |
payment_facilitator_url | Url del facilitador de pago | < 76 AN | SÍ |
phone_number | Número de teléfono | < 15 N | SÍ |
mcc | Código de comercio (Merchant Category Code) | < = 4 N | SÍ |
Respuesta:
Parámetros de respuesta
| Parámetro | Descripción | Formato |
|---|---|---|
code | Código de respuesta de Carat. Cualquier código distinto de 0 indica un error. Más información: | < 4 N |
message | Mensaje de respuesta de Carat. | < 500 AN |
| capture | ||
authorizer_code | Código de respuesta del autorizador. | < 10 AN |
authorizer_message | Mensaje de respuesta del autorizador. | < 500 AN |
status | Estado de la transacción de pago en Carat. Más información: | = 3 AN |
nit | Identificador de la transacción de pago en Carat. | = 64 AN |
order_id | Código de pedido enviado por la tienda al crear la transacción. | < 40 AN |
customer_receipt | Comprobante (para el cliente). | < 4000 AN |
merchant_receipt | Comprobante (para el establecimiento). | < 4000 AN |
authorizer_id | Número de secuencia único enviado por la tienda al crear la transacción. | < 12 N |
acquirer_id | Código del adquirente utilizado en la transacción. | < 4 N |
acquirer_name | Nombre del adquirente utilizado en la transacción. | < 100 AN |
authorizer_date | Fecha de efectivización del pago devuelta por el autorizador en formato DD/MM/AAAA'T'HH:mm. Ejemplo: 13/07/2017T16:03 | = 16 D |
authorization_number | Número de autorización. | < 6 AN |
merchant_usn | Número de secuencia único enviado por la tienda al crear la transacción. | < 12 N |
esitef_usn | Número de secuencia único de la transacción de pago en Carat. | = 15 N |
sitef_usn | Número de secuencia único de la transacción de pago en SiTef. | = 6 N |
host_usn | NSU de la autorizadora. Observación para la concreción de pagos PIX. | < 15 AN |
amount | Valor de la compra especificado por la tienda (en centavos) al crear la transacción. | < 12 N |
payment_type | Tipo de pago de la autorizadora seleccionada: B = boleto, C = crédito, D = débito, P = tarjeta de crédito Private Label puro, T = transferencia bancaria, G = tarjeta de regalo, O = otros medios de pago, W = Boleto NR vía Web Service | = 1 AN |
Cancelación#
El proceso de cancelación requiere autenticación con firma por defecto, ver detalles en Pago en línea | Cancelación y sigue el pedido a continuación. Nota: Para las transacciones ya capturadas también será posible utilizar la Cancelación Asincrónica, ver detalles en Pago en línea | Cancelación Asincrónica
- Recurso:
/e-sitef/api/v2/cancellations/{{nit}} - Método HTTP:
POST - Formato da solicitud:
JSON - Formato da respuesta:
JSON - Parámetros de encabezado:
| Parámetro | Descripción | Formato | Obligatorio |
|---|---|---|---|
merchant_id | Código de tienda en el Portal Carat. Los códigos de producción y certificación serán diferentes. | < 15 AN | SI |
merchant_key | Clave de autenticación para la tienda de Pagos Online. 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 |
Authorization | La firma de autenticación de la tienda debe enviarse en el formato Bearer {firma}". Ejemplo: Bearer JHVGytfdgauygdauiw78264284527852897hagdg`. Este campo es obligatorio, a menos que la tienda esté configurada para comunicarse con autenticación mutua (mTLS) con Carat. | < 2000 AN | COND. |
Ejemplo#
Para usar este ejemplo, no olvides definir la variable {{url}} con el valor
esitef-homologacao.softwareexpress.com.br
Pedido:
Parámetros del pedido
| Parámetro | Descripción | Formato | Requerido |
|---|---|---|---|
amount | Valor total de la compra (en centavos). Ejemplo: 1,00 = 100 o 1.100,00 = 110000 – enviar el valor sin la coma y punto. | < 12 N | SÍ |
mcc | Código de comercio (Merchant Category Code) | < = 4 N | SÍ |
| subacquirer_merchant | Datos del subadquirente | ||
id | Id del subseller | = 15 N | SÍ |
address | Dirección del subseller | < 120 AN | SÍ |
city | Ciudad | < 20 AN | SÍ |
state | Provincia | < 30 AN | SÍ |
country | País según código numérico de la ISO 3166 | < 3 N | SÍ |
zip_code | Código postal | < 8 N | SÍ |
identification_number | Número de identificación del subseller | < 18 N | SÍ |
payment_facilitator_id | Id del facilitador de pago (Si no llega a 11 caracteres, añade ceros a la izquierda) | = 11 N | SÍ |
payment_facilitator_url | Url del facilitador de pago | < 76 AN | SÍ |
phone_number | Número de teléfono | < 15 N | SÍ |
Respuesta:
Parámetros de respuesta
| Parámetro | Descripción | Formato |
|---|---|---|
code | Código de respuesta de Carat. Cualquier código distinto de 0 indica un error. Más información: | < 4 N |
message | Mensaje de respuesta de Carat. | < 500 AN |
| cancellation | ||
authorizer_code | Código de respuesta del autorizador. | < 10 AN |
authorizer_message | Mensaje de respuesta del autorizador. | < 500 AN |
status | Estado de la transacción de pago en Carat. Más información: | = 3 AN |
nit | Identificador de la transacción de pago en Carat. | = 64 AN |
order_id | Código de pedido enviado por la tienda al crear la transacción. | < 40 AN |
customer_receipt | Comprobante (para el cliente). | < 4000 AN |
merchant_receipt | Comprobante (para el establecimiento). | < 4000 AN |
authorizer_id | Número de secuencia único enviado por la tienda al crear la transacción. | < 12 N |
acquirer_id | Código del adquirente utilizado en la transacción. | < 4 N |
acquirer_name | Nombre del adquirente utilizado en la transacción. | < 100 AN |
authorizer_date | Fecha de efectivización del pago devuelta por el autorizador en formato DD/MM/AAAA'T'HH:mm. Ejemplo: 13/07/2017T16:03 | = 16 D |
authorization_number | Número de autorización. | < 6 AN |
merchant_usn | Número de secuencia único enviado por la tienda al crear la transacción. | < 12 N |
esitef_usn | Número de secuencia único de la transacción de pago en Carat. | = 15 N |
sitef_usn | Número de secuencia único de la transacción de pago en SiTef. | = 6 N |
host_usn | NSU de la autorizadora. Observación para la concreción de pagos PIX. | < 15 AN |
amount | Valor de la compra especificado por la tienda (en centavos) al crear la transacción. | < 12 N |
payment_type | Tipo de pago de la autorizadora seleccionada: B = boleto, C = crédito, D = débito, P = tarjeta de crédito Private Label puro, T = transferencia bancaria, G = tarjeta de regalo, O = otros medios de pago, W = Boleto NR vía Web Service | = 1 AN |
esitef_date | Fecha de efectivización del cancelamento en Carat en formato DD/MM/AAAA'T'HH:mm. Ejemplo: 13/07/2017T16:03 | = 16 D |
is_host_cancel | Este campo retornará el valor true en caso de cancelación vía host. | < 5 T/F |