Card payments through files
Here we explain the structure of the files for creation of Token.
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.
Shipping files
The token creation file must fulfill the following characteristics:
File naming
The file name should be: TK + [MERCHANT ID] + [DATE] + [FILE NUMBER].txt
- FILE TYPE: TK for Tokens 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
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.
Example of an answer file name TKmzdtln0bmtms6o3kck8f2017062701RSP.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. |
respose_code | 6 | Numeric | Global process code.0000 = Successful.Other error See error codes. |
Card migration file
Creating tokens (DTL)
Field | Required | Size | Type | Description |
---|---|---|---|---|
record_type | Yes | 3 | Alfanumeric | Fixed Value: DTL |
record_number | Yes | 6 | Numeric | Consecutive record number. |
holder_name | Yes | 200 | Alfanumeric | Cardholder name. |
card_number | Yes | 16-19 | Numeric | Card number can be 16 or 19 digits. |
cvv2 | No | 3-4 | Numeric | Security code as it appears on the back of the card. Usually 3 digits. |
expiration_month | No | 2 | Numeric | Expiration month as it appears on the card. |
expiration_year | Yes | 2 | Numeric | Year of expiration as it appears on the card. |
address.city | No | Alfanumeric | Cardholder City. | |
address.country_code | No | 2 | Alfanumeric | Cardholder country code to two characters in format ISO_3166-1 |
address.postal_code | No | 5 | Numeric | Zip code of the cardholder. |
address.line1 | No | 100 | Alfanumeric | First line of address of the cardholder. Commonly used to indicate street and exterior and interior number. |
address.line2 | No | 100 | Alfanumeric | Second line of the cardholder's address. Usually used to indicate condominium, suite or delegation. |
address.line3 | No | 100 | Alfanumeric | Third line of cardholder address. Commonly used to indicate colony. |
address.state | No | 50 | Alfanumeric | Cardholder status. |
Tokens register file
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
Reply by Tokens (DTL)
Field | Size | Type | Description |
---|---|---|---|
record_type | 3 | Alfanumeric | Fixed Value: DTL |
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. |
respose_code | 4 | Numeric | The code of the answer.0000 = Successful.Other error = See error codes. |
description | 100 | Alfanumeric | Detail of the error occurred. |
token_id | 20 | Alfanumeric | Card ID generated in Openpay. |
Reply to file tokens
DTL|01|data|3013|Invalid verifier digit|
DTL|02||0000|Created|kxnqb1y62cggher82tae
DTL|03||0000|Created|ktv5ocwyohro61xmzs38
DTL|04||0000|Created|koaayegrixktpfwsqdqn
TRL|05|
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 | Event type |
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
Event | Category | Description |
---|---|---|
batch.file.started | files | Start processing a file. |
batch.file.finished | files | The processing of a file has been completed. |
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 test cards
- Implement Notifications to know the status of payments in real time