Card payments through files

We present a new way to charge Card; here we explain the structure of the files for token charges, this are required by Openpay for the integration of card charges through files.

Is important to register the cards to use in the charge creation file, the merchant must ask the buyer for the data of his card and register it in Openpay, if the merchant requires to use the card data more than once the id of the token must be stored to send it in subsequent charges and NEVER store the card data.

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

  1. The merchant generates the Charges File with the tokens generated by Openpay.
  2. The merchant sends the Charges File which will be processed by Openpay.
  3. Openpay downloads file generated by the merchant.
  4. Openpay notifies the trade via Webhook that the processing of the file of charges has begun.
  5. Openpay generates a Response File for the merchant, which will contain the result of each of the charges made.
  6. 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

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

Example of a token file name TKmzdtln0bmtms6o3kck8f2017062701.txt

File Structure

Any token or charge creation file must have one or more detail records (DTL) and a summary record (TRL) that will be used to verify the total number of lines contained in the file.
The separator of the fields will be the pipe character “|”.
The file encoding should be UTF-8.
The expected end of the line is unix type "\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.txt

Example of an answer file name CGmzdtln0bmtms6o3kck8f2017062701RSP.txt

In case the file has structure error, the response file will contain a single detail record (DTL) with error code 9999 error in the file structure, and with the detail of the error in the description column.

When the file is processed correctly it must contain a record for each record in the input file, it is recommended that to relate the records of the input file to the output file is used the data in the column order_id, the response file to just as the input file will contain a summary log.

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.

category

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
    }
}

Event types

Item

Category

Description

batch.file.started

Files

Start processing a file.

batch.file.finished

Files

The processing of a file has been completed.

File types

Prefix

Type

Error Codes

Code

Cause

3001

Card declined.

3002

Card is expired.

3003

Card has not enough funds.

3004

Card has been flagged as stolen.

3005

Card has been rejected by the antifraud system.

3006

The operation is not allowed for this customer or transaction.

3007

Deprecated. The card was rejected.

3008

The card doesn’t support online transactions.

3009

Card has been flagged as lost.

3010

The card has been restricted by the bank.

3011

The bank has requested to hold this card. Please contact the bank.

3012

Bank authorization is required to make this payment.

9000

The file is empty.

9001

Summary record (TRL) is invalid.

9002

Total summary records do not match the number of records.

9999

File structure error.

Notes:

  • You can simulate different results using the cards Testing
  • Implement the Notifications to know the status of payments in real time