Archivos batch
Aquí te explicamos la estructura de los archivos para la migración de tarjetas a través de archivos.
Nota: Para poder utlizar este medio de pago deberás contactar con nuestra area de soporte para realizar las configuraciones necesarias en tu cuenta y activar esta caracteristica.
Archivos de envío
Tanto el archivo de migracion de tarjetas debe 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: TK para archivo de Token.
- 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.
Ejemplo de un nombre de archivo de tokens TKmzdtln0bmtms6o3kck8f2017062701.txt
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.
Ejemplo de un nombre de archivo de respuesta TKmzdtln0bmtms6o3kck8f2017062701RSP.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.
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. |
respose_code | 6 | Numérico | Código global del proceso.0000 = Exitoso.Otro error = Ver códigos de error. |
Migración de tarjetas
Creación de 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. |
holder_name | Sí | 200 | Alfanumérico | Nombre del tarjeta habiente. |
card_number | Sí | 16-19 | Numérico | Número de tarjeta puede ser de 16 o 19 dígitos. |
cvv2 | No | 3-4 | Numérico | Código de seguridad como aparece en la parte de atrás de la tarjeta. Generalmente 3 dígitos. |
expiration_month | No | 2 | Numérico | Mes de expiración tal como aparece en la tarjeta. |
expiration_year | Sí | 2 | Numérico | Año de expiración tal como aparece en la tarjeta. |
address.city | No | Alfanumérico | Ciudad del tarjeta habiente. | |
address.country_code | No | 2 | Alfanumérico | Código del país del tarjeta habiente a dos caracteres en formato ISO_3166-1 |
address.postal_code | No | 5 | Numérico | Código postal del tarjeta habiente |
address.line1 | No | 100 | Alfanumérico | Primera línea de dirección del tarjeta habiente. Usada comúnmente para indicar la calle y número exterior e interior. |
address.line2 | No | 100 | Alfanumérico | Segunda línea de la dirección del tarjeta habiente. Usada comúnmente para indicar condominio, suite o delegación. |
address.line3 | No | 100 | Alfanumérico | Tercera línea de la dirección del tarjeta habiente. Usada comúnmente para indicar la colonia. |
address.state | No | 50 | Alfanumérico | Estado del tarjeta habiente. |
Archivo de registro de tokens
DTL|01|Victor Flores|5546293000053692|937|07|20|Queretaro|MX|76927|Av. revolucion No 15|El marquez|Las Hadas|Querétaro
DTL|02|Noe Diezmarin|4152313000795398|308|12|21|Cuernavaca|MX|65234|Av. de la acordada No 4|Villaflores|La Troje|Morelos
DTL|03|Gonzalo Suarez|4005520000000129|425|04|20|Pachuca|MX|36467|Calle Luis Vega No 5|Miradores|Centro|Hidalgo
DTL|04|Francisco Mata|5413330089010483|364|10|22|Aguascalientes|MX|20119|Manuel Clouthier No 4|Anahuac||Aguascalientes
TRL|05|04
Respuesta de Tokens (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. |
respose_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. |
token_id | 20 | Alfanumérico | Id de tarjeta generado en Openpay. |
Respuesta del archivo de tokens
DTL|1|data|3013|Invalid verifier digit|
DTL|2||0000|Created|kxnqb1y62cggher82tae
DTL|3||0000|Created|ktv5ocwyohro61xmzs38
DTL|4||0000|Created|koaayegrixktpfwsqdqn
TRL|5|4|3|1|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 | Tipo de evento |
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. |
error_code | Numérico | Código de error. Si fue un procesamiento exitoso se enviará el código 0000. |
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
Evento | 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 |
---|---|
TK | Creación de tokens |
CG | Cargos con token |
RF | Devoluciones |
SC | Subscripciones |
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