Archivos batch

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.

Cargos con Archivos

  1. El comercio genera el Archivo de Cargos con los tokens generados en Openpay.
  2. El comercio envía el Archivo de Cargos el cual será procesado por Openpay.
  3. Openpay descarga el archivo de Cargos generado por el comercio.
  4. Openpay notifica al comercio vía Webhook que se ha iniciado el procesamiento del archivo de cargos.
  5. Openpay genera un Archivo de respuesta para el comercio, el cual contendrá el resultado de cada uno de los cargos realizados.
  6. 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

  1. TIPO DE ARCHIVO: CG para el archivo de creación de cargos y RF para el archivo de reembolsos.
  2. ID COMERCIO: Identificador del comercio de 20 caracteres en Openpay.
  3. FECHA: Fecha de generación del archivo en formato (YYYYMMDD).
  4. NUMERO DE ARCHIVO: Un número consecutivo del archivo por día.

Ejemplo de un nombre de archivo de tokens CGmzdtln0bmtms6o3kck8f2017062701.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.

[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.

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

3

Alfanumérico

Valor Fijo: DTL

record_number

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

45

Alfanumérico

ID de la tarjeta guardada o el id del token creado de donde se retirarán los fondos.

amount

9

Alfanumérico

Cantidad del cargo. Debe ser una cantidad mayor a cero, con hasta dos dígitos decimales.

currency

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

250

Alfanumérico

Descripción asociada al cargo.

name

100

Alfanumérico

Nombre(s) del cliente.

last_name

100

Alfanumérico

Apellidos del cliente.

email

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.

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

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