Servicio de ejecución de pagos
Después de consumir el servicio de creación de transacciones y obtener un NIT, puede continuar con el siguiente paso en el flujo: la llamada al servicio de ejecución de pagos. Esta operación también debe consumirse en los flujos de pago programados. En este caso, Portal Carat garantiza que la cita solo se activará si se confirma el pago.
Detalles de la llamada#
- Recurso:
/v1/payments/{nit} - Método HTTP:
POST - Formato de la solicitud:
JSON - Formato de la 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 |
comerciante_clave | 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 |
Ejemplos#
A continuación, se muestran algunos ejemplos de llamadas al servicio de pago mediante la herramienta cURL.
Pago con captura automática#
Solicitud:
Respuesta:
Pago con confirmación tardía#
Solicitud:
Respuesta:
Pago agendado#
Solicitud:
Respuesta:
Pago con tarjeta almacenada#
Solicitud:
Respuesta:
Pago con prefijos#
Solicitud:
Respuesta:
Pago dividido para rutas BIN y Sipag a través de SiTef#
Solicitud:
Respuesta:
Reintentar pago#
Solicitud:
Respuesta:
Pago - Token de marca de tarjeta#
Algunas marcas de tarjetas poseen una solución de tokenización que ofrece el almacenamiento de tarjetas en cajas fuertes en la propia marca, de forma encriptada. Esta tokenización de marca tiene como objetivo mejorar la seguridad y la calidad de la información de la tarjeta transmitida, lo que conduce a posibles aumentos en la conversión de la aprobación por parte de los bancos emisores.
Solicitud:
Respuesta:
Códigos de respuesta
Ver referencia en Códigos API - Códigos de respuesta
Parámetros de solicitud#
En la siguiente tabla, hay una descripción de los parámetros de solicitud del servicio de pago:
| Parámetro | Descripción | Formato | Obligatorio |
|---|---|---|---|
authorizer_id | Código de autorizador en el Portal Carat. Más información. Si este campo no se envió en la etapa de creación de la transacción, se vuelve obligatorio al momento de consumir el servicio de pago. | < 3 N | COND. |
customer_postal_code | Código postal (CEP en Brasil) del usuario. Esto debe enviarse para transacciones enrutadas de iCards a través de SiTef, si su colección está indicada en el servicio de búsqueda de tarjetas mediante el campo is_customer_postal_code_required. | < 8 N | COND. |
mcc | El MCC (Merchant Category Code) es un código que clasifica una empresa por el tipo de bienes o productos suministrados. | < 4 N | NO |
subacquirer_merchant_id | Identificación de la tienda en el sub adquirente. | < 22 N | NO |
| card | Datos de la tarjeta. | ||
number | Número de tarjeta del comprador (PAN). Token generado por la tarjeta (DPAN) para pago con token de marca de tarjeta. Más información | < 19 N | SÍ |
cryptogram | Criptograma generado por la tarjeta. | = 28 A | Sí para pagos con token de marca de tarjeta |
expiry_date | Fecha de vencimiento de la tarjeta en formato MMAA. Su obligación depende del comprador elegido. En la mayoría de los casos, este campo es obligatorio. | = 4 N | COND. |
security_code | Código de seguridad. Este campo puede no ser obligatorio si la empresa tiene un acuerdo en el contrato firmado con las redes adquirentes, solo para el pago de ciertos segmentos. Sin embargo, es posible configurar el campo obligatorio en la configuración de la tienda, consulte el soporte de Carat para obtener más información. Importante: un pago con horario agendado implica el almacenamiento de la tarjeta comprador de datos en el entorno de Portal Carat. Sin embargo, por razones de seguridad, el código de seguridad no se puede almacenar. Por tanto, los pagos programados siempre se ejecutarán sin enviar el código de seguridad. | < 5 N | COND. |
holder | Nombre del tarjetahabiente. | < 30 AN | COND. |
token | HASH de una tarjeta almacenada en Portal Carat. No está permitido enviar un número de tarjeta abierta (campo número) y una tarjeta almacenada (campo token) en la misma solicitud. | = 88 AN | NO |
wallet_transaction_id | ID de una transacción de billetera digital. Por ahora, esta funcionalidad solo está disponible para los autorizadores Visa Checkout, VEE (a través de CardSE-SiTef) y Google Pay. No está permitido enviar un número de tarjeta abierta (campo número), una tarjeta almacenada (campo token) y un wallet_transaction_id en la misma solicitud. | < 25 AN | NO |
initial_wallet_transaction_id | Le dice si la ID de Wallet (wallet_transaction_id) se está utilizando por primera vez. Si es la primera vez, envíe "true"; de lo contrario, envíe "false". | < 5 T / F | NO |
wallet_type | Campo que especifica si la transacción se procesa con PAN o DPAN. Si "tipo" está vacío, el valor predeterminado es PAN (número de tarjeta no tokenizado). Si hay una transacción tokenizada, debes enviar el valor “network_token”. | AN | NO |
| external_authentication | Este elemento recibe campos de resultado de autenticación MPI. | ||
version | Versión de 3DS utilizada en el proceso de autenticación (actualmente solo se acepta la versión 2) | < 1 AN | NO |
eci | Indicador de comercio electrónico: indica el nivel de seguridad de la transacción con autenticación del titular de la tarjeta | < 3 N | NO |
reference_id | Identificador de la transacción de autenticación del titular de la tarjeta, realizada en un servicio externo a Carat (en nuestro Web Checkout, reference_id está referenciado por ds.transId en el retorno de autenticación de 3DS) | < 40 N | NO |
cavv | Valor de verificación de autenticación del titular de la tarjeta: código que indica el resultado de la autenticación del titular de la tarjeta. | < 40 N | NO |
| acquirer | Se requieren datos específicos según el adquirente / enrutamiento. | ||
financing_plan | Código del plan de financiación. Requerido solo para pagos a plazos que devengan intereses enrutados por Via Certa Financiadora a través de SiTef. | < 4 N | NO |
special_code | Código de uso general de Conductor / Renner. | < 6 N | NO |
recurrency | Flag que define si se paga y el no. | 5 T/F | NO |
recurrency_tid | TID de la primera transacción en repetición. Identificador que diferencia la primera recurrencia de las posteriores. | < 16 AN | NO |
recurrency_original_amount | Valor original de la transacción que inició la recurrencia. Este valor debe ser informado en todas las recurrencias posteriores. Se usa solo para la recurrencia. Campo utilizado solo en enrutamiento BIN, obligatorio cuando haya recurrencia | < 18 AN | NO |
product_code | Código de producto. Es obligatorio en el enrutamiento vía Marisa. | < 6 N | COND. |
terminal | Terminal SiTef que desea utilizar. Si no se envía, PayPal generará una terminal aleatoria. | = 14 N | NO |
company_code | Código de la empresa SiTef que desea utilizar. Si no se envía, PayPal enviará el código de empresa registrado en la tienda. | = 8 N | NO |
authorization_number | Código de Autorización. Obligatorio para el autorizador de Bradescard Voucher | < 6 AN | COND. |
| acquirer.vouchers_filter[] | Filtro de Vouchers: elección de cupones que no se aceptarán. Opciones de "Vouchers": 01 - Alimentación, 02 - Comida 03 - Cultura, 04 - Combustible, 05 - Beneficio. Ejemplo: No se aceptan cupones: Cultura, Combustible, Beneficio. Debe enviar: "vouchers_filter": ["03", "04", "05"] | ||
| acquirer.prefixes | Elemento para enviar prefijos SiTef, como CYCLES, CPLANO y VLRADD. Si el prefijo enviado no es compatible con la tarjeta enviada, Portal Carat invalidará la transacción, evitando que se dé una falsa impresión del uso de una determinada funcionalidad. Ejemplo: { "key" : "value" } -> { "CICLOS" : "01" } | ||
key | Nombre de prefijo. | < 1024 AN | NO |
value | Valor de prefijo. | < 1024 AN | NO |
| acquirer.submerchant_split[] | Consiste en una matriz para pagos divididos, exclusiva para enrutamiento BIN y Sipag, ambos a través de SiTef. Permite dividir partes del monto total del pago entre otras empresas. El número máximo de elementos permitidos en esta matriz es de 5 elementos. Cada elemento se compone de los campos submechant_code y submerchant_amount. | ||
submerchant_code | Código de establecimiento BIN / Sipag | < 51 AN | NO |
submerchant_amount | valor de transacción para el establecimiento | < 12 N | NO |
| acquirer.card_on_file | Está destinado al envío de información específica como, por ejemplo, la autorización de almacenamiento de la tarjeta, confirmando que el titular de la tarjeta ha autorizado el almacenamiento de la misma. Más información. | ||
usage | Indica el uso. Por ejemplo, en caso de autorización de almacenamiento: authorized | < 11 AN | NO |
reason | Indica el motivo. Por ejemplo, en caso de autorización de almacenamiento: card | < 11 AN | NO |
ATENCIÓN: Los parámetros
terminalycompany_codesolo deben usarse para enrutamiento a través de SiTef y deben enviarse simultáneamente.
También es necesario solicitar permiso al equipo de servicio de Portal Carat Permite el envío de Company y Sitef Terminal vía REST .
Parámetros de respuesta#
Si tiene éxito, el código de respuesta HTTP será "201". Cualquier otro código debe interpretarse como un error. En la siguiente tabla se muestra la descripción de los parámetros de respuesta del servicio de realización de pagos:
| Parámetro | Descripción | Formato |
|---|---|---|
code | Código de respuesta de Portal Carat. Cualquier código que no sea "0" significa error. [Más información.] (Api-codes.md # response-codes) | < 4 N |
message | Mensaje de respuesta de Portal 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 Portal Carat. [Más información.] (codigos-da-api.md#status-de-transacões-do-e-sitef) | = 3 AN |
nit | Identificador de la transacción de pago en PayPal. | = 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 |
sitef_usn | Número secuencial único de la transacción de pago de SiTef. | = 6 N |
sitef_usn | Número secuencial único de la transacción de pago en Pagamento Online. | = 15 N |
customer_receipt | Cupón (a través del cliente). | < 4000 AN |
comerciante_receipt | Cupón (vía establecimiento). | < 4000 AN |
authorizer_id | Código de autorización utilizado en la transacción. | < 4 N |
adquisr_id | Código del adquirente utilizado en la transacción. | < 4 N |
adquirr_name | Nombre del adquirente utilizado en la transacción. | < 100 AN |
authorizer_date | Fecha de vigencia del pago devuelta por el autorizador en formato DD / MM / AAAA'T'HH: mm. Ejemplo: 07/13 / 2017T16: 03 | = 16 D |
número_autorización | Numero de autorización. | < 6 AN |
host_usn | Autorizador NSU. Advertencia para realizar pagos PIX. Más información | |
| < 15 AN | ||
tid | ID de transacción en el adquirente. Este campo solo se devuelve en transacciones con adquirentes que no son SiTef. | < 40 AN |
payment_date | Fecha de vigencia del pago en Portal Carat en el formato DD / MM / AAAA'T'HH: mm. Ejemplo: 07/13 / 2017T16: 03 | = 16 D |
issuer | Marca el código devuelto por el autorizador. | < 5 AN |
authorizer_merchant_id | Código de afiliación del comerciante con la agencia autorizadora. | < 100 AN |
xid | Campo XID devuelto en autenticaciones 3DS o ciertos adquirentes. | < 40 AN |
balance | Saldo disponible después del pago con tarjetas de regalo. | < 12 N |
recurrency_tid | Id. De transacción (TID) de la bandera, que se refiere a la primera transacción de la recurrencia. Solo se devuelve cuando es una recurrencia. | < 16 AN |
retryable_code | Indicador de reversibilidad de una transacción cuya autorización fue denegada por el autorizador. Este campo será devuelto en la respuesta a la solicitud de pago con tarjeta y deberá ser tomado en cuenta en el mecanismo de reintento de transacciones de la tienda en línea. Códigos válidos:01 – Transacción denegada reversible, retener más tarde. 02 – Transacción denegada irreversible, no retentiva. | = 2 N |
| payment.analysis | ||
code | Código de respuesta de la operación de análisis de fraude. | < 4 N |
message | Mensaje de respuesta a la operación de análisis de fraude. | < 200 AN |
status | Estado de transacción de análisis de fraude de Portal Carat. Este campo puede tomar los siguientes valores: NOV - Nuevo. EXP - Caducado. ACC - Aceptado REJ - Rechazado REV - En revisión INV - No válido | = 3 AN |
| schedule | ||
status | Estado de la agenda en el Portal Carat. [Más información.] (codigos-da-api.md#status-de-agendamento) | = 3 AN |
sid | Identificador de la transacción de reserva en Portal Carat. | = 64 AN |
schedule_usn | Número secuencial único del Portal Carat. | = 15 N |
authorizer_id | Código de autorización que se utilizará en pagos programados. En operaciones con tarjeta tokenizada, si no se informa al autorizador, se utilizará el código autorizador utilizado en el almacenamiento de la tarjeta. | = 4 N |
amount | Cantidad de pagos programados especificados por la tienda (en centavos) en la creación de la transacción. | < 12 N |
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 |
initial_date | Fecha de ejecución del primer pago programado en formato "DD / MM / AAAA". | = 10 D |
next_date | Fecha de ejecución del próximo pago programado en formato "DD / MM / AAAA". | = 10 D |
number_of_times | Número total de pagamentos agendados. | < 3 N |
installments | Número de cuotas que se utilizarán para los pagos programados. | < 2 N |
installment_type | Tipo de financiación que se utilizará para los pagos agendados. | < 2 N |
soft_descriptor | Texto adicional que aparecerá con el nombre del establecimiento en el extracto de la tarjeta de crédito del comprador. | < 30 AN |
show_times_invoice | Para agendas de tiempo finitos, si este campo tiene un valor de true , agrega el número de ejecuciones / ejecuciones totales al final del campo soft_descriptor (ejemplo: Suscripción 3/12). | < 5 T / F |
terminal_id | Código de terminal utilizado en la transacción | < 8 AN |
recurrency_tid | Id. De transacción (TID) de la bandera, que se refiere a la primera transacción de la recurrencia. Solo se devuelve cuando es una recurrencia. | < 16 AN |
Parámetros de Card-On-File#
Card on File se refiere a transacciones que involucran el almacenamiento de información de tarjetas de crédito para uso futuro. Estas transacciones indican que una tarjeta se ha almacenado de forma segura en un sistema, lo que permite utilizarla más tarde sin tener que volver a introducir los datos de la tarjeta. La opción de almacenar la tarjeta ofrece comodidad a los usuarios al permitirles realizar pagos de transacciones futuras de forma rápida y sencilla. Además, los emisores de tarjetas también pueden utilizar el almacenamiento de información de la tarjeta para el análisis de riesgos y la prevención del fraude, mejorando la seguridad de las transacciones y aumentando la tasa de conversión.
Para las operaciones de Card-On-File, se deben enviar los siguientes parámetros:
| acquirer.card_on_file | ||
|---|---|---|
usage | Identifica el uso | - authorized - first - subsequent |
reason | Identificar la razón | - card - recurring - cardholder - unscheduled |
Definiciones#
Se aceptan los siguientes valores para los parámetros usage y reason, dentro de acquirer.card_on_file:
usage | Definición |
|---|---|
first | Indicar la primera ocurrencia |
subsequent | Indicar ocorrencias posteriores de una recurrencia |
authorized | Para utilizar junto con el parámetro reason=card para indicar que el titular de la tarjeta ha autorizado el almacenamiento de la misma |
reason | Definición |
|---|---|
cardholder | Compras posteriores provocadas por el titular de la tarjeta |
unscheduled | Compras posteriores sin programar |
recurring | Compras recurrentes programadas |
installment | Cuota por recurrencia |
card | Debe utilizarse junto con el parámetro usage=authorized para indicar que el titular de efectivo ha autorizado el almacenamiento de la tarjeta |
MIT y CIT#
Hay dos tipos de transacciones con tarjeta registrada: CIT (Transacción iniciada por el titular de la tarjeta) y MIT (Transacción iniciada por el comerciante)
| Sigla | Definición |
|---|---|
| CIT | Es cualquier transacción en la que el titular de la tarjeta participa activamente en la transacción, ya sea en una terminal en la tienda o através de una experiencia de pago online. |
| MIT | Es una transacción posterior con las credenciales ya almacenadas, para la cual el titular de la tarjeta ha dado su consentimiento previo al comerciante para almacenar las credenciales de pago para uso futuro, sin su participación activa. Tal sería el caso de la facturación automática de los servicios de suscripción, por citar un ejemplo. |
Combinaciones válidas#
usage | reason | Definición | ¿MIT/CIT? |
|---|---|---|---|
authorized | card | Indica que el titular de la tarjeta ha autorizado el almacenamiento de la tarjeta | CIT |
first | unscheduled | Indica un pago único | MIT |
first | recurring | Indica la primera la primera ocurrencia de una recurrencia | MIT |
subsequent | recurring | Indica ocurrencias posteriores de una recurrencia | MIT |
subsequent | cardholder | Indica un pago realizado por el usuario con la tarjeta ya almacenada | CIT |
subsequent | unscheduled | Indica una ocurrencia posterior no programada iniciada por el comerciante | MIT |
subsequent | installment | Indica cuota por periodicidad | MIT |
Recurrencia#
Los pagos recurrentes son transacciones con tarjeta de crédito que ocurren periódicamente y se repiten después de un cierto período de tiempo. Un ejemplo común se encuentra en las suscripciones, donde el comprador desea que se le cobre automáticamente, sin tener que volver a ingresar los datos de la tarjeta de crédito para cada transacción. En este tipo de pago, el cliente autoriza previamente cargos periódicos, estableciendo las condiciones y el intervalo de tiempo entre transacciones. Esto proporciona comodidad tanto para el comprador, que no tiene que preocuparse por realizar pagos repetidos manualmente, como para el vendedor, que mantiene una fuente constante de ingresos.
Para operaciones de recurrencia, se deben enviar los siguientes parámetros:
Acquirer | ||
recurrency | Indica que este pago es parte de una recurrencia | - true - false |
recurrency_tid | TID de la primera transacción que provocó la recurrencia. | |
recurrency_original_amount | Valor original de la transacción que originó la recurrencia. Este valor debe ser informado en todas las recurrencias posteriores. Obligatorio solo para ELO | |
Acquirer.card_on_file | ||
usage | Identifica el uso | - first - subsequent |
reason | Identifica el motivo | - recurring |
Wallet ID | DPAN/Cartera Digital |
Ejemplo#
Solicitud original
Para usar este ejemplo y los demás, no olvide establecer la variable {{url}} en el valor
sandbox.ecomm-bin.fiserv.com.br
Pedido:
Respuesta:
El parámetro recurency_tid de la solicitud anterior se usa en todas las solicitudes posteriores. También tenga en cuenta los parámetros de la estructura card_on_file que cambian en la primera solicitud de la recurrencia y en las solicitudes posteriores (segunda y posteriores).
Primer pago recurrente
Pedido:
Respuesta:
Solicitud posterior de recurrencia
Pedido:
Respuesta: