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 planes de financiamiento Via Certa Financiadora
Atención: Es importante que en la creación de la transacción el
cuotaes mayor que1por cuota.
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. Requerido solo para pagos con e-Rede, GetNet WS y VR (SmartNet). | < 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. Aceptado para todos los enrutamientos a través de SiTef, Cielo e-Commerce, Stone WS, Global Payments WS, SafraPay, e.Rede REST y GetnetWS. En caso de recursividad a través de Stone WS, es obligatorio enviar solo un campo adicional a continuación, is_first_recurring The is_subsequent_recurring. | 5 T/F | NO |
recurrency_tid | TID de la primera transacción en repetición. Identificador que diferencia la primera recurrencia de las posteriores. Solo se usa cuando se trata de una recurrencia. Campo utilizado únicamente en el enrutamiento REST de e.Rede para las marcas Visa y Mastercard y en el enrutamiento GetnetWS. | < 16 AN | NO |
is_first_recurring | Flag utilizada en solitario para el enrutamiento de StoneWS. Indica que la transacción es la primera de una serie de transacciones recurrentes. | < 5 T/F | COND. |
is_subsequent_recurring | Flag utilizada en solitario para el enrutamiento de StoneWS. Indica que la transacción es la segunda o la enésima de una serie de transacciones recurrentes, donde n > 2. | < 5 T/F | COND. |
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 |
eci | Indicador de comercio electrónico(indicador del nivel de seguridad de las transacciones de pago a través de Cielo e-Commerce). | < 3 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 |
authentication_url | URL de autenticación devuelta en los flujos de pago con autenticación. Solo disponible para Cielo e-Commerce. | < 56 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. Campo utilizado solo en el enrutamiento REST e.Rede para las marcas Visa y Mastercard. | < 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. Campo utilizado solo en el enrutamiento REST e.Rede para las marcas Visa y Mastercard. | < 16 AN |