Te presentamos una nueva forma de hacer operaciones con tarjeta; en esta guía te explicamos la estructura de los archivos para realizar cargos con token, devoluciones y creación de suscripciones.
Para poder utilizar estas operaciones es necesario contar con el token de la tarjeta, el cual lo puedes crear usando la guía de Cargos con token (Puntos 1 al 4), si requieres utilizar los datos de la tarjeta más de una vez se deberás almacenar el id del token para enviarlo en cargos posteriores para hacer esto consulta la guía de OneClick.
Nota: Para poder utlizar archivos deberás contactar con nuestra área de soporte para realizar las configuraciones necesarias en tu cuenta y activar esta caracteristica.
[TIPO DE ARCHIVO] + [ID COMERCIO] + [FECHA] + [NUMERO ARCHIVO] + RSP.txt Ejemplo de un nombre de archivo de respuesta CGmzdtln0bmtms6o3kck8f2017062701RSP.txt
En caso de que el archivo tenga error de estructura, el archivo de respuesta contendrá un solo registro de detalle (DTL) con el código de error 9999 error en la estructura del archivo, y con el detalle del error en la columna descripción.
Cuando el archivo sea procesado correctamente deberá contener un registro por cada registro existente en el archivo de entrada, se recomienda que para relacionar los registros del archivo de entrada con el de salida se utilice la del dato de la columna order_id, el archivo de respuesta al igual que el archivo de entrada contendrá un registro de sumarizado.
Nota: Para poder utlizar archivos deberás contactar con nuestra área de soporte para realizar las configuraciones necesarias en tu cuenta y activar esta caracteristica.
Cargos con Archivos
- El comercio genera el Archivo de Cargos con los tokens generados en Openpay.
- El comercio envía el Archivo de Cargos el cual será procesado por Openpay.
- Openpay descarga el archivo de Cargos generado por el comercio.
- Openpay notifica al comercio vía Webhook que se ha iniciado el procesamiento del archivo de cargos.
- Openpay genera un Archivo de respuesta para el comercio, el cual contendrá el resultado de cada uno de los cargos realizados.
- Openpay notifica al comercio vía Webhook de que se ha finalizado el procesamiento del archivo de cargos.
Archivos de envío
Tanto el archivo de creación de Token como el de realizar cargo deben cumplir con las siguientes características:Nombrado de archivo
El nombre de archivo deberá ser [TIPO DE ARCHIVO] + [ID COMERCIO] + [FECHA] + [NUMERO DE ARCHIVO].txt- TIPO DE ARCHIVO: CG para el archivo de creación de cargos y RF para el archivo de reembolsos.
- ID COMERCIO: Identificador del comercio de 20 caracteres en Openpay.
- FECHA: Fecha de generación del archivo en formato (YYYYMMDD).
- NUMERO DE ARCHIVO: Un número consecutivo del archivo por día.
Estructura de Archivos
Todo archivo ya sea de token o de creación de cargos deberá tener uno o varios registros de detalle (DTL) y un registro de sumarizado (TRL) que servirá para verificar el total de lineas contenidas en el archivo. El separador de los campos será el carácter de pipe “|”. La codificación del archivo deberá ser UTF-8. El fin de linea que se espera es tipo unix “\n”.Archivos de respuesta
Por cada archivo enviado a Openpay, se deberá responder un archivo con las siguientes características:Nombrado de archivo
El nombre de archivo deberá ser el mismo que el archivo de entrada más la cadena fija RSP que indica que es un archivo de respuesta.Registro de Sumarizado (TRL)
Campo
Tamaño
Tipo
Descripción
record_type
3
Alfanumérico
Valor Fijo: DTL
record_number
6
Numérico
Número de registro consecutivo.
total_rows
6
Numérico
Número de registros contenidos en el archivo.
total_success
6
Numérico
Número de registros procesados exitosamente.
total_failed
6
Numérico
Número de registros fallidos.
response_code
6
Numérico
Código global del proceso.
0000 = Exitoso.
Otro error = Ver códigos de error.
Cargos con token
Realizar cargos a tokens (DTL)
Campo
Requerido
Tamaño
Tipo
Descripción
record_type
Sí
3
Alfanumérico
Valor Fijo: DTL
record_number
Sí
6
Numérico
Número de registro consecutivo.
order_id
No
100
Alfanumérico
Identificador único del cargo. Debe ser único entre todas las transacciones.
token
Sí
45
Alfanumérico
ID de la tarjeta guardada o el id del token creado de donde se retirarán los fondos.
amount
Sí
9
Alfanumérico
Cantidad del cargo. Debe ser una cantidad mayor a cero, con hasta dos dígitos decimales.
currency
Sí
3
Alfanumérico
Tipo de moneda del cargo. Por el momento solo se soportan 2 tipos de monedas: Pesos Mexicanos(MXN) y Dólares Americanos(USD).
description
Sí
250
Alfanumérico
Descripción asociada al cargo.
name
Sí
100
Alfanumérico
Nombre(s) del cliente.
last_name
Sí
100
Alfanumérico
Apellidos del cliente.
Sí
100
Alfanumérico
Cuenta de correo electrónico del Cliente.
phone_number
No
100
Alfanumérico
Número telefónico del Cliente.
Archivo de petición de cargo
DTL|01|O-00016|kbsdfvndvptoy3q9yc1i|20.00|MXN|Cobro de servicio|Victor|Flores|vflores@hotmail.com|
DTL|02|O-00017|kxnqb1y62cggher82tae|16.00|USD|Cargo mensual|Noe|Diezmarin|Noe.diezamrin@gmail.com|5534775453
DTL|03|O-00018|ktv5ocwyohro61xmzs38|19.30|MXN|Servicio de agosto|Gonzalo|Suarez|gonzoflores@msn.com|
DTL|04|O-00019|koaayegrixktpfwsqdqn|25.91|MXN|Cargo de suscripción|Francisco|Mata|franmata@live.com|
TRL|05|04
Respuesta de Archivo de Cargos (DTL)
Campo
Tamaño
Tipo
Descripción
record_type
3
Alfanumérico
Valor Fijo: DTL
record_number
6
Numérico
Número de registro consecutivo.
category
5
Alfanumérico
data: Indica un error causado por datos enviados en el archivo.
internal: Indica un error interno en el procesamiento o al momento de hacer el cargo y debe ser enviado nuevamente.
response_code
4
Numérico
El código de la respuesta.
0000 = Exitoso.
Otro error = Ver códigos de error.
description
100
Alfanumérico
Detalle del error ocurrido.
subscription_id
20
Alfanumérico
Identificador único de Openpay asociado a la subscripción.
customer_id
20
Alfanumérico
Identificador único de Openpay asociado al cliente.
creation_date
26
Fecha
Fecha de creación de la transacción en formato ISO 8601.
Ejemplo: 2013-11-14T18:29:35-06:00.
Respuesta del archivo de subscripciones
DTL|1|data|9999|Record have an invalid format|||2017-11-08T10:45:04-06:00
DTL|2|data|1005|The requested resource doesn't exist|||2017-11-08T10:45:04-06:00
DTL|3||0000||s7wwnydwbw4tpoj2wenl|afeptixwgeamr0xga64c|2017-11-08T10:45:35-06:00
DTL|4||0000||s6avrtvj75qwcaq6ttmh|arpc4fzscguo061bl7no|2017-11-08T10:45:36-06:00
DTL|5||0000||sxzaittouuamqlmbuqne|a7ekvidkz7dnjfs0ohgn|2017-11-08T10:45:36-06:00
TRL|6|5|3|2|0000|
Webhooks
Openpay notificara lanzando una petición POST hacia un endpoint alojado en la aplicación del comercio. Opcionalmente el comercio puede proporcionar el usuario y password para que Openpay lánze la petición utilizando Basic Authentication.
En el cuerpo de la petición será agregado un JSON con la información relacionada al evento y al archivo que fue procesado.
Elemento
Tipo
Descripción
type
String
El código de la respuesta.
0000 = Exitoso.
Otro error = Ver códigos de error.
event_date
Date
Fecha en la cual fue lanzado el webhook.
inputBatchFile
Objeto
Objeto el cual contiene el resumen del archivo.
file_name
String
Nombre del archivo.
public_id
String
Identificador único del archibo dentro de Openpay.
begin_date
Date
Fecha en la cual el archivo empezó a procesarse.
finish_date
Date
Fecha en la cual el archivo se terminó de procesar.
total_records
Numérico
Total de registros procesados.
type
String
Tipo de archivo. cards ó charges.
failed_records
Numérico
Cantidad de registros que fueron procesados con errores.
success_records
Numérico
Cantidad de registros que fueron procesados de forma exitosa.
status
String
Estado del archivo. in_progress ó processed.
POST https://mi-comercio/charges/files HTTP/1.1
Authorization: Basic VEVTVDp0ZXN0
Content-Type: application/json
{
"type": "batch.file.finished",
"event_date": "2017-10-06T14:02:15-05:00",
"inputBatchFile": {
"file_name": "TKm9blej0uw9lcq2scykny2017100301.txt",
"public_id": "bch1urwc0b2dofnpl2cb",
"begin_date": "2017-10-05T12:00:04-05:00",
"finish_date": "2017-10-05T12:00:12-05:00",
"total_records": 7,
"type": "cards",
"failed_records": 0,
"success_records": 7,
"status": "completed",
"error_code": 0000
}
}Tipos de eventos
Elemento
Categoria
Descripción
batch.file.started
Archivos
Inicio de procesamiento de un Archivo
batch.file.finished
Archivos
Se ha concluido el procesamiento de un Archivo
Tipos de archivos
Prefijo
Tipo
Códigos de Error
Código
Causa
3001
La tarjeta fue declinada.
3002
La tarjeta ha expirado.
3003
La tarjeta no tiene fondos suficientes.
3004
La tarjeta ha sido identificada como una tarjeta robada.
3005
La tarjeta ha sido rechazada por el sistema antifraudes.
3006
La operación no esta permitida para este cliente o esta transacción.
3007
Deprecado. La tarjeta fue declinada.
3008
La tarjeta no es soportada en transacciones en línea.
3009
La tarjeta fue reportada como perdida.
3010
El banco ha restringido la tarjeta.
3011
El banco ha solicitado que la tarjeta sea retenida. Contacte al banco.
3012
Se requiere solicitar al banco autorización para realizar este pago.
9000
El archivo esta vacío.
9001
El registro del resumen (TRL) es inválido.
9002
El total de registros del resumen no coincide con el número de registros.
9999
Error en la estructura del archivo.
Notas:
- Puedes simular diferentes resultados usando las tarjetas de Pruebas
- Implementa las Notificaciones para conocer el estado de los pagos en tiempo real
