EPX
The merchant can configure Carat Portal transactions to be routed by several payment providers. One of them is EPX.
Supported Carat Portal interfaces#
The following interfaces are available for integrations with EPX:
- REST Pre-Authorization
- REST Payment
- REST Cancel
- HTML Payment
- HTML Pre-Authorization
Required credentials#
The merchant must obtain from EPX the credentials listed below and send them to Software Express or register them on Carat Portal's merchant's portal.
| Parameter | Description |
|---|---|
CUST_NBR | The sponsoring merchant bank level of hierarchy within EPX internal systems. |
MERCH_NBR | The "settle to" level of hierarchy within EPX internal systems, and contains the account numbers for settlement. |
DBA_NBR | The "doing business as" (DBA) level of hierarchy within EPX internal systems, and contains descriptor information.. |
TERMINAL_NBR | The terminal (the device or service that is capturing the transactions) level of hierarchy within EPX internal systems. The terminal can be a physical device, website, virtual terminal, etc. |
Transaction creation service parameters#
Request#
| Parameter | Description | Format | Required |
|---|---|---|---|
amount | Total price of the purchase (in cents). Example: 1,00 = 100 or 1.100,00 = 110000 – send the value without the comma and the dots. | < 12 N | Yes |
merchant_usn | Unique sequential number for each order, created by the merchant. | < 12 N | No |
order_id | Order code defined by the merchant. It's advised that it is different for each order so that it becomes easier to track it. | < 40 AN | No |
soft_descriptor | Additional text that will be presented alongside the name of the establishment in the credit card invoice. | < 30 A | No |
additional_data Additional fields | |||
tax_amount | Tax amount which is included in the amount of the transaction. | < 12 N | No |
tax_exempt | Indicates whether the transaction is tax-free. It can receive the following values: Y - transaction is tax exempt. N - transaction is not tax exempt and tax amount needs to be provided. | < 1 A | No |
tip_amount | Tip amount included in the transaction amount. | < 12 N | No |
additional_data.extra_param Extra parameters | |||
acquirer_params[] | Optional fields that the merchant can use to store additional information about the transaction. | < 80 AN | No |
additional_data.payer Customer data | |||
born_date | Costumer birth date, in AAAA-MM-DDTHH:MM:SS. e.g. 1991-01-02T08:30:00 | 19 N | No |
name | Customer name | < 25 A | No |
surname | Customer surname | < 25 A | No |
identification_number | Customer ID (CPF/RG). | < 20 AN | No |
additional_data.payer.address Customer address | |||
street_name | Customer street name. This field will be sent to EPX concatenated with street_number. | < 30 AN | No |
street_number | Customer street number. | < 30 AN | No |
state | Customer state address. Ex.: SP | < 2 A | No |
zip_code | Customer zip code address | < 9 AN | No |
additional_data.payer.phones Customer phone info | |||
number | Customer phone number. | < 10 N | No |
type | Field used to differentiate phone types: 6 - Cell phone 2 - Commercial 1 - Residential | 1 N | No |
Transaction creation service request example#
Payment and pre-authorization effectuation services parameters#
Request#
| Parameter | Description | Format | Required |
|---|---|---|---|
card Card data | |||
number | Customer's card number (PAN). | < 19 N | Yes |
barcode_data | Contains the data of the barcode. This field must be sent with the acquirer.input_type value of A and supports the unencrypted PAN or TLV Visa formats. Learn more. | < 100 AN | No |
id | Code that represents the industry used for the transaction requested. It can receive the following values: 0 - Card holder present 1 - Card holder not present M - Card holder present, card not readable | < 1 AN | No |
security_code | Card security code. | < 4 N | No |
expiry_date | Card expiry date in MMYY format. | 4 N | No |
issue_number | Credit card's issue number. | < 3 N | No |
issue_date | Credit card's issue date in MMYY format. | < 4 A | No |
card.crypto Card encryption data | |||
type | Identifies which type of encryption is in use. 0 - Use the acquirer.input_type field to identify Format 1 - MagTek V2 Format 2 3DES Format (generic) | 1 N | No |
card.crypto Card EMV chip Data | |||
data | This field holds the EMV tags of transactions using an EMV chip. | < 510 AN | No |
track_1 ou track_2 | Track data from the credit or debit card. track_1 must be used when processing a credit card transaction, and track_2 must be used if track_1 is unavailable or when processing a debit or EBT transaction. | < 256 AN | No |
acquirer Acquirer data | |||
aci | The Authorization Characteristics Indicator (ACI) field is used to identify specific characteristics of the transaction for the Networks. It can receive the following values: R - Recurrying transaction P - Transaction is an installment | 1 AN | No |
input_type | Indicates how the card number was entered for the transaction. It can receive the following values: X - Typed A - Bar code H - Track 1 D - Track 2 | 1 A | Yes |
cash_back_amount | Cash back amount (in cents) | < 12 N | No |
reference_number | This is a required field for PIN-less Debit transactions that contain the consumer's account information, such as electrical, telephone, loan, or policy number for the bill that is being paid during the transaction. | < 25 AN | No |
operator_code | User name of the person running the application that is submitting the transaction. | < 25 A | No |
soft_descriptor_2 | This field is used to replace the City/State section of the Merchant Descriptor on the cardholder statement. | < 40 A | No |
terminal Terminal data | |||
chip_conditions | This field is used to indicate the reason for the EMV fallback transaction: 0 - Not applicable to fallback transactions. For VSDC transactions must be 0 1 - Transaction was initiated from a magnetic stripe with a service code beginning with 2 or 6 and the last read at VSDC terminal was a successful chip read or was not a chip transaction. 2 - Transaction was initiated at a chip-capable terminal from a magnetic stripe that contains service code 2 or 6, and the previous transaction initiated by that terminal was an unsuccessful chip read. | 1 N | No |
authentication Authentication data | |||
authentication.pin PIN authentication data | |||
value | Encrypted PIN. Mandatory when the cardholder types the password online. | < 64 AN | No |
authentication.pin.crypto PIN authentication encryption data | |||
ksn | PIN encryption KSN. Mandatory when the cardholder types the password online. | < 20 AN | No |
barcode_data field details#
| Position | Size | Format | Description |
|---|---|---|---|
| 1-3 | 3 | N | Type: - 000 = PAN - No encryption - 001 = Visa - TLV - No encryption |
| 4-N | Variable | ANS | Bar code data |
Payment service request example#
To use this example, don't forget to define the variable {{url}} with the value
esitef-homologacao.softwareexpress.com.br
Response Parameters#
| Parameter | Description | Format |
|---|---|---|
balance | Current balance after payments with voucher cards (in cents). | < 12 N |
avs_result | Address Verification System response for the requested transaction. | 1 A |
authorization_number | Authorization number. | < 6 AN |
cvv2_response | CVV2 response for the requested transaction. | 1 A |
emv_data | EMV data | < 510 AN |
tid | EPX transaction ID. | < 20 AN |
authorizer_response_code | EPX response code. | < 3 AN |
authorizer_response_message | EPX response message. | < 80 AN |
authorizer_date | Payment authorization date returned by the authorizer in DD/MM/AAAA'T'HH:mm. Example: 13/07/2017T16:03 | 16 AN |