Getting Started

Guides

Reference

Plugins

Card payments through files

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.
Note: In order to use this payment method you must contact our support area to do the necessary settings in your account and activate this feature.

Flow of Charges with Files

The merchant generates the Charges File with the tokens generated by Openpay.
The merchant sends the Charges File which will be processed by Openpay.
Openpay downloads file generated by the merchant.
Openpay notifies the trade via Webhook that the processing of the file of charges has begun.
Openpay generates a Response File for the merchant, which will contain the result of each of the charges made.
Openpay notifies to the merchant via Webhook that the processing of the file of charges has been completed.

Shipping files

Both the token creation file and the token file must fulfill the following characteristics:

File naming

The file name should be: [FILE TYPE] + [MERCHANT ID] + [DATE] + [FILE NUMBER].txt

FILE TYPE:TK for Token File and CG for the file of the Charges Creation File.
MERCHANT ID: Openpay 20 character merchant identifier.
DATE: Date of generation of the file in format (YYYYMMDD).
FILE NUMBER: A consecutive file number per day.

Example of a token file name TKmzdtln0bmtms6o3kck8f2017062701.txt

File Structure

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

Reply files

For each file sent to Openpay, a file with the following characteristics must be answered:

File naming

The file name must be the same as the input file plus the fixed RSP string indicating that it is a response file. [FILE TYPE] + [MERCHANT ID] + [DATE] + [FILE NAME] + RSP.txtEjemplo 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.

Summary Record (TRL)

Field

Size

Type

Description

record_type

3 Alfanumeric

Fixed Value: TRL

record_number

6 Numeric

Consecutive record number.

total_rows

6 Numeric

Number of records contained in the file.

total_success

6 Numeric

Number of records processed successfully.

total_failed

6 Numeric

Number of failed records.

response_code

6 Numeric

Global process code.

0000 = Successful.
Other error = See error codes.

Charges with tokens

Charges with tokens (DTL)

Field

Required

Size

Type

Description

record_type

Yes

3 Alfanumeric

Fixed Value: TRL

record_number

Yes

6 Numeric

Consecutive record number.

order_id

No

100 Alfanumeric

Unique identifier of the position. Must be unique among all transactions.

token

Yes

45 Alfanumeric

ID of the saved card or token id created from where the funds will be withdrawn.

amount

Yes

9 Alfanumeric

Amount of charge. Must be an amount greater than zero, with up to two decimal digits.

currency

Yes

3 Alfanumeric

Type of currency of charge. At the moment only two types of currencies are supported: Mexican Pesos (MXN) and American Dollars (USD).

description

Yes

250 Alfanumeric

Description associated with the charge.

name

Yes

100 Alfanumeric

Customer's name(s).

last_name

Yes

100 Alfanumeric

Customer's last name.

email

Yes

100 Alfanumeric

Customer's email.

phone_number

No

100 Alfanumeric

Customer's telephone number.

Charges file

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

Load File Response (DTL)

Field

Size

Type

Description

record_type

3 Alfanumeric

Fixed Value: TRL

record_number

6 Numeric

Consecutive record number.

5 Alfanumeric

data: Indicates an error caused by data sent in the file.
internal: Indicates an internal error in the processing or at the time of the charge and must be sent again.

response_code

4 Numeric

The code of the answer.

0000 = Successful.
Other error = See error codes.

description

100 Alfanumeric

Description associated with the error.

subscription_id

20 Alfanumeric

Openpay Subscriptions identifier.

customer_id

20 Alfanumeric

Openpay Customer identifier.

creation_date

26 Date

Creation date of the transaction in format ISO 8601.
Example: 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 will notify by launching a POST request to an endpoint hosted in the Merchant application. Optionally the merchant can provide the user and password for Openpay to read the request using Basic Authentication.

In the body of the request will be added a JSON with the information related to the event and the file that was processed.

Item

Type

Description

type

String

The code of the answer.

0000 = Successful.
Other error = See error codes.

event_date

Date

Date on which the webhook was launched.

inputBatchFile

Objeto

Object containing the file summary.

file_name

String

File name.

public_id

String

Unique identifier of the file inside Openpay.

begin_date

Date

Date on which the file was processed.

finish_date

Date

Date on which the file was finished processing.

total_records

Numeric

Total records processed.

type

String

File type cards or charges.

failed_records

Numeric

Number of records that were processed with errors.

success_records

Numeric

Number of records that were processed successfully.

status

String

File Status. in_progress or processed.

error_code

Numeric

Error code.
If successful processing will send the code 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
    }
}