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
- 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
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 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: DTL |
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 | Numeric | 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. |
Yes | 100 | Alfanumeric | Customer's email. | |
phone_number | No | 100 | Alfanumeric | Customer's telephone number. |
Charges file
Load File Response (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. |
response_code | 4 | Numeric | The code of the answer.0000 = Success.Other error See error codes. |
description | 100 | Alfanumeric | Detail of the error occurred. |
authorization | 6 | Alfanumeric | Authorization number of the position. |
transaction_id | 20 | Alfanumeric | Openpay unique identifier. |
order_id | 100 | Alfanumeric | Unique identifier of the position. Must be unique among all transactions. |
creation_date | 26 | Date | Creation date of the transaction in format ISO 8601.Example: 2013-11-14T18:29:35-06:00. |
Charge file response
Refunds
Refunds (DTL)
Field | Required | Size | Type | Description |
---|---|---|---|---|
record_type | Yes | 3 | Alfanumeric | Fixed Value: DTL |
record_number | Yes | 6 | Numeric | Consecutive record number. |
transaction_id | Yes | 20 | Alfanumeric | Openpay unique identifier. |
token | No | 20 | Alfanumeric | ID of the card. |
amount | No | 9 | Numeric | Amount of charge. Must be an amount greater than zero, with up to two decimal digits. |
description | No | 250 | Alfanumeric | Description associated with the charge. |
Refunds file
Refunds reply (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. |
response_code | 4 | Numeric | The code of the answer.0000 = Success.Other error See error codes. |
description | 100 | Alfanumeric | Description associated with the error. |
authorization | 6 | Alfanumeric | Authorization number of the position. |
transaction_id | 20 | Alfanumeric | Openpay transaction identifier. |
refund_id | 20 | Alfanumeric | Openpay refund identifier. |
creation_date | 26 | Date | Creation date of the transaction in format ISO 8601.Example: 2013-11-14T18:29:35-06:00. |
Refunds file reply
Subscriptions
Subscriptions (DTL)
Field | Requered | Size | Type | Description |
---|---|---|---|---|
record_type | Yes | 3 | Alfanumeric | Fixed Value: DTL |
record_number | Yes | 6 | Numeric | Consecutive record number. |
plan_id | Yes | 20 | Alfanumeric | Unique plan identifier. |
trial_end_date | No | 10 | Fecha | Indicates the customer trial end date. If it’s not indicated the plan will be used to calculate it. If the date is in the past it will be interpreted as a subscription with no trial. Format: yyyy-mm-dd. |
name | No | 100 | Alfanumeric | Customer's name(s). |
last_name | No | 100 | Alfanumeric | Customer's last name. |
Yes | 100 | Alfanumeric | Customer's email. | |
phone_number | No | 100 | Alfanumeric | Customer's telephone number. |
token | Yes | 45 | Alfanumeric | ID of the saved card or token id created from where the funds will be withdrawn. |
Subscriptions file
Subscriptions reply (DTL)
Field | Length | Size | 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. |
response_code | 4 | Numeric | The code of the answer.0000 = Success.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. |
Subscriptions reply
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. |
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. |
File types
Prefix | Type |
---|---|
TK | Create tokens |
CG | Charges with tokens |
RF | Refunds |
SC | Subscriptions |
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