Servicio de recarga
Detalles de la llamada#
- Recurso:
/ v3 / recharge/{nit} - Método HTTP:
PUT - Formato de solicitud:
JSON - Formato de respuesta:
JSON - Parámetros de encabezado:
| Parámetro
| Descripción
| Formato | Obligatorio |
| --------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------- | ----------- |
| Content-Type | Debe enviarse con el valor application/json. | = 15 AN | SÍ |
| Authorization | Firma de autenticidad en formato Bearer {assinatura}. sepa mas.
Ejemplo: Bearer hh39458f73hf45324765ft349h5f73t4h95f34.
Este campo es obligatorio si la transacción fue creada por el proceso de firma. | < 2000 AN | COND. |
Ejemplos#
Abajo, se muestran ejemplos de llamadas al servicio de recarga con la herramienta cURL.
Recarga normal con pago#
Solicitud:
Para usar este ejemplo, no olvide definir la variable {{url}} con el valor
esitef-homologacao.softwareexpress.com.br
Respuesta:
Recarga normal sin pago#
Solicitud:
Para usar este ejemplo, no olvide definir la variable {{url}} con el valor
esitef-homologacao.softwareexpress.com.br
Respuesta:
Recarga tipo others#
Solicitud:
Para usar este ejemplo, no olvide definir la variable {{url}} con el valor
esitef-homologacao.softwareexpress.com.br
Respuesta:
Recarga tipo invoice#
Solicitud:
Para usar este ejemplo, no olvide definir la variable {{url}} con el valor
esitef-homologacao.softwareexpress.com.br
Respuesta:
Parámetros de solicitud#
En la tabla abajo describe los parámetros de solicitud del servicio de recarga:
| Parámetro
| Descripción
| Formato | Obligatorio |
| ----------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :-------------: | :---------------------: |
| nit | Identificación de transacción de recarga de pago
Online | = 64 AN | SÍ |
| amount | Cantidad de recarga, en centavos | < 12 N
| SÍ |
| amount_key | Código de valor de recarga | < 10 AN | NO |
| terminal_type | 01 - PDV02 - TU03 - TAS04 - Internet05 - POS-Sitef/POS | = 2 N | NO |
| cpf | CPF del cliente | < 20 AN | NO |
| cnpj | CNPJ del cliente | < 20 AN | NO |
| zip_code | Código postal del cliente | < 9 AN | NO |
| |
general | CCódigo de identificación de tabla con datos relacionados con recargas (operadores, sucursales, escalones de valores, validaciones de crédito, entre otros). | = 16 AN | NO |
| | code | Código del distribuidor/operador | < 3 N | SÍ |
| type_code | Código de tipo de distribuidor/operador | < 2 N | SÍ |
| dealer.branch | code | Código de sucursal del concesionario/operador. Obligatorio solo para el tipo de recarga others. | 11 N | COND. |
| | phone.ddd | Código DDD del teléfono. Requerido solo para el tipo de recarga normal. | = 2 N | COND. |
| phone.number | Numero de teléfono. Requerido solo para el tipo de recarga normal. | < 9 N | COND. |
| | Este campo agrega una lista de respuestas. Necesario si se han recibido preguntas en el listado de datos de la sucursal. | |
code | Código de pregunta a responder | < 20 AN | COND. |
| description | Pregunta respuesta | < 200 AN | COND. |
| | Este objeto contiene campos obligatorios para el pago sin factura (tipo de recarga
invoice). |
| bar_code | Código de barras de la factura elegida. | = 48 N | SÍ al tipo invoice |
| description | Descripción de la factura elegida. | < 64 AN | SÍ al tipo invoice |
| expiry_date | Fecha de vencimiento de la factura elegida en formato DDMMAAAA. | = 8 N | SÍ al tipo invoice |
| reference_data | Datos de referencia de la factura elegida. | < 32 AN | SÍ al tipo invoice |
| echo | Valor de campo echo recibido en el listado de datos de la sucursal. | < 11 N | SÍ al tipo invoice |
| | Este elemento solo debe enviarse si desea realizar un pago vinculado a la recarga. \
Atención: El pago solo está permitido en el tipo de recarga
normal. Para el tipo de recarga others, la transacción será nula. |
| amount | Monto del pago, en centavos | < 12 N | SÍ* |
| authorizer_id | Código de autorizador en el Portal Carat. Sepa mas. | < 5 N | SÍ* |
| customer_id | Documento de identidad del comprador. Utilice solo caracteres alfanuméricos | < 20 AN | NO |
| merchant_key | Clave de la tienda registrada en el Portal Carat. Debe ser la misma tienda utilizada para realizar la recarga. | < 80 AN | SÍ* |
| | number | Número de plazos | < 2 N | SÍ* |
| type | Tipo de financiación a plazos: 3 - cuotas con intereses de la empresa de la tarjeta, 4 - cuotas realizadas por la tienda y sin intereses. (Adopte este valor como predeterminado / predeterminado para transacciones en efectivo) 6 - pago a plazos con intereses del administrador (IATA) 7 - pago a plazos realizado por la tienda sin intereses (IATA) | = 1 N | SI \ |
| number | Numero de tarjeta. | < 19 N | SÍ \ |
| token | Token de tarjeta almacenado en Portal Carat. | = 88 AN | SÍ \ |
| security_code | Código de Seguridad de la Tarjeta. Campo opcional, si se envía, se utilizará el código principal de la empresa SiTef, no la recurrencia (que no requiere un código de seguridad). Su obligación depende del contrato firmado con Card Adm. | < 5 N | COND. |
| expiry_date | Fecha de vencimiento en formato "MMAY" | = 4 N | SÍ \ * |
| | Este campo agrega una lista de parámetros adicionales. | |
key | Tecla de parámetro adicional | N / A | NO |
| value | Valor de parámetro adicional | N / A | NO |
| | Métodos de pago utilizados. Este campo agrega una lista de valores que deben enviarse como se describe en el capítulo siguiente.
Envio do campo used_payment_methods#
La tienda debe utilizar el campo used_payment_methods para indicar a Portal Carat qué métodos de pago se utilizaron para pagar una transacción específica, como una recarga.
La cantidad de datos que se escribirán en el campo used_payment_methods está limitada por el campo payment_methods.max. Si, por ejemplo, se recibió el valor 3 en el campo payment_methods.max, entonces la tienda solo puede almacenar 3 piezas de información en el campo used_payment_methods.
Para cada método de pago utilizado, se debe registrar un elemento (datos) en el campo used_payment_methods. Los datos que se registrarán en el campo used_payment_methods tienen el siguiente formato:
TipoN:ValorN:IDColetaN1:DadoColetaN1-IDColetaN2:DadoColetaN2-...-IDColetaNn:DadoColetaNn
Dónde:
TipoN: indica el método de pago utilizado (como se muestra en la tabla anterior).ValorN: indica el monto utilizado con este método de pago, con dos decimales, sin la coma.IDColetaNn: indica el ID del campo que fue recolectado por la tienda (según la tabla ya presentada arriba).DadoColetaNn: indica el contenido recopilado por la tienda para este campo.
Comentarios:
Si para una determinada forma de pago la tienda no debe recopilar ningún campo, el campo used_payment_methods debe valorarse con los siguientes datos: TypeN: ValueN.
La consistencia de los valores (suma de las distintas formas de pago utilizadas, totalizando el valor de la transacción realizada) debe ser realizada por la tienda, y Portal Carat solo utilizará los valores en la forma en que fueron enviados.
Ejemplo
Supongamos que al ejecutar una transacción de recarga, la tienda obtuvo el valor 2 al leer el campo payment_methods.max y los siguientes valores del campo used_payment_methods:
'' 00 02: 03-07-10-13 (5.125) 03:10 ''
El valor 2 recibido en el campo payment_methods.max, indica a la tienda que solo puede pagar la recarga con un máximo de 2 métodos de pago diferentes.
Suponiendo que la tienda pagó la recarga de la siguiente manera: BRL 30,00 en efectivo y BRL 20,00 con una tarjeta de débito procesada por la red adquirente Rede (Red de destino = 5; Host NSU = 123456789; Datos de confirmación = 0520200001A6) . En este caso, el campo used_payment_methods debe valorarse con los siguientes datos:
Envío de los datos de la tarjeta para el pago#
Si desea enviar el token de la tarjeta almacenado en Pagamento Online, los otros datos de la tarjeta (card.number, card.expiry_date) no serán considerados.
Si desea enviar datos de tarjetas abiertas, no debe enviar el token.
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 siguiente tabla, hay una descripción de los parámetros de respuesta del servicio de recarga:
| Parámetro | Descripción | Formato |
|---|---|---|
status | Status de la transacción de recarga de Portal Carat. [Más información.] (codigos-da-api.md#status-de-transacões-do-e-sitef) | = 3 AN |
order_id | Código de pedido generado por la tienda. | < 20 AN |
merchant_usn | NSU de transacción generada por la tienda. | < 12 N |
tv_package_subscription_codes[] | Códigos de suscripción de paquetes de TV. | < 32 AN |
resubmit_transaction | Si este campo recibe el valor true, la tienda debe reenviar la solicitud de recarga con el campo answers completado de la siguiente manera:"answers":[{"code":"126","description":"<um dos códigos recebidos no campo tv_package_subscription_codes>"}] En este caso, el status de la transacción se devolverá como AGU. Este flujo solo es posible cuando se realiza la recarga de TV. | T / F |
send_payment_methods | Marca de la tarjeta que indica que los métodos de pago deben enviarse en la próxima transacción. Tendrá el valor true si es positivo. | < 5 AN |
| esitef | ||
code | Código de respuesta de Portal Carat. Cualquier código que no sea 0 (cero) significa falla. [Más información.] (codigos-da-api.md#codigos-de-resposta) | < 4 N |
message | Mensaje de respuesta de Portal Carat. | < 500 AN |
usn | Transacción de recarga de Portal Carat NSU | = 15 N |
| sitef | ||
code | Código de respuesta SiTef | = 3 AN |
message | Mensaje de respuesta de SiTef | < 500 AN |
| anfitrión | ||
code | Código de respuesta devuelto por el autorizador | < 4 AN |
message | Mensaje devuelto por el autorizador | < 64 AN |
| acquirer
| branch_code | Recargar código de afiliado | < 5 N |
| merchant_code | Código de la tienda registrada con el adquirente | < 15 N |
| authorization
| confirmation_data| Código de confirmación | < 128 AN |
| authorizer_date | Fecha de autorización en el autorizador en formato "MMDD" | = 4 N |
| authorizer_time | Hora de autorización en el autorizador en formato HHmmSS | = 6 N |
| host_usn | Anfitrión NSU | < 20 N |
| sitef_usn | SiTef NSU | < 10 N |
| number | Número de autorización en el autorizador | < 6 N |
| customer
| total_copies | Número de copias del recibo del cliente | < 2 N |
| receipt | Cupón de cliente | < 4000 AN |
|merchant |
| total_copies | Número de copias del bono del establecimiento | < 2 N |
| receipt | Comprobante de establecimiento | < 4000 AN |
| hashes | La consistencia de los valores (suma de las distintas formas de pago utilizadas, totalizando el valor de la transacción realizada) debe ser realizada por la tienda, y Portal Carat solo utilizará los valores como fueron enviados.
Ejemplo
Supongamos que al ejecutar una transacción de recarga, la tienda obtuvo el valor 2 al leer el campo payment_methods.max y los siguientes valores del campo used_payment_methods:
El valor 2 recibido en el campo payment_methods.max, indica a la tienda que solo puede pagar la recarga con un máximo de 2 métodos de pago diferentes.
Suponiendo que la tienda pagó la recarga de la siguiente manera: BRL 30,00 en efectivo y BRL 20,00 con una tarjeta de débito procesada por la red adquirente Rede (Red de destino = 5; Host NSU = 123456789; Datos de confirmación = 0520200001A6) . En este caso, el campo used_payment_methods debe valorarse con los siguientes datos:
| general | Tabla de código de identificación con datos relacionados con recargas (operadores, sucursales, rangos de valor, validez crediticia, entre otros). | = 16 AN |
| wallet | Hash de carteras digitales. | < 32 AN |
payment_methods |
| max | Número máximo de métodos de pago | < 2 N |
|payment_methods.available[]| Este campo agrega una lista de métodos de pago disponibles. |
| name | Nombre del método de pago disponible. [Más información.] (recarga-rest-listBranchData.md#retorno-do-campo-payment_methodsavailable) | < 200 AN |
| payment | Este elemento solo se devuelve si se ha enviado un pago vinculado a la recarga. |
| 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 |
| amount | Importe del pago, el mismo que se envió cuando se creó la transacción de pago. | < 12 AN |
| 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 gift O= otros métodos de pago
authorizer_id | Id del autorizador en el Portal Carat donde se realizó el pago | < 5 N |
| acquirer | Tipo de pago | < 50 AN |
| payment.esitef|
usn | NSU del Portal Carat | < 15 AN |
| date | Fecha de pago en formato DD / MM / AAAA hh: mm en Portal Carat. | < 19A |
| pago.sitiof |
| code | Código de respuesta devuelto por SiTef | = 3 AN |
| payment.customer |
| receipt | Comprobante de pago (a través del cliente) | < 4000 AN |
| payment.merchant |
| receipt | Comprobante de pago (a través del establecimiento) | < 4000 AN |
| payment.authorization |
| number | Número de autorización de pago | < 6 AN |
| sitef_usn | SiTef NSU | < 15 AN |
| host_usn | Autorizador NSU | < 15 AN |
| tid | ID de transacción en el autorizador, devuelto para algunos tipos de pago. | < 40 AN |
| eci | Indicador de comercio electrónico devuelto por algunos tipos de pago. | < 3 AN |
| sitef_date | Fecha de pago en formato DD / MM / AAAA hh: mm en SiTef. | < 19 AN |
| payment.analysis ||
status | Status de la transacción en la institución de revisión. | = 3 AN |
| code | Código de respuesta al análisis de riesgos. | < 4 AN |
| message | Mensaje de respuesta al análisis de riesgos. | < 100 AN |
| payment.extra_param[]|
key | Tecla de parámetro adicional | N / A |
| value | Valor de parámetro adicional | N / A |Importante:
En el caso de recargas de otros productos (
others) que involucren pins (por ejemplo, pines de juego), el pin se devolverá una vez , como parte del campopayment.customer.receipt. Como es un campo sensible, Portal Carat no lo almacena, por lo que las consultas de estado posteriores no devolverán el pin. Si hay algún problema después de que Portal Carat devuelva el pin, no se podrá recuperar y será necesario generar otro.