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.

CUST_NBRThe sponsoring merchant bank level of hierarchy within EPX internal systems.
MERCH_NBRThe "settle to" level of hierarchy within EPX internal systems, and contains the account numbers for settlement.
DBA_NBRThe "doing business as" (DBA) level of hierarchy within EPX internal systems, and contains descriptor information..
TERMINAL_NBRThe 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#


amountTotal 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 NYes
merchant_usnUnique sequential number for each order, created by the merchant.< 12 NNo
order_idOrder code defined by the merchant. It's advised that it is different for each order so that it becomes easier to track it.< 40 ANNo
soft_descriptorAdditional text that will be presented alongside the name of the establishment in the credit card invoice.< 30 ANo
additional_data Additional fields
tax_amountTax amount which is included in the amount of the transaction.< 12 NNo
tax_exemptIndicates 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 ANo
tip_amountTip amount included in the transaction amount.< 12 NNo
Extra parameters
acquirer_params[]Optional fields that the merchant can use to store additional information about the transaction.< 80 ANNo
Customer data
born_dateCostumer birth date, in AAAA-MM-DDTHH:MM:SS. e.g. 1991-01-02T08:30:0019 NNo
nameCustomer name< 25 ANo
surnameCustomer surname< 25 ANo
identification_numberCustomer ID (CPF/RG).< 20 ANNo
Customer address
street_nameCustomer street name. This field will be sent to EPX concatenated with street_number.< 30 ANNo
street_numberCustomer street number.< 30 ANNo
stateCustomer state address. Ex.: SP< 2 ANo
zip_codeCustomer zip code address< 9 ANNo
Customer phone info
numberCustomer phone number.< 10 NNo
typeField used to differentiate phone types:
6 - Cell phone
2 - Commercial
1 - Residential
1 NNo

Transaction creation service request example#

--request POST "https://esitef-homologacao.softwareexpress.com.br/e-sitef-hml/api/v1/transactions"
--header "Content-Type: application/json"
--header "merchant_id: xxxxxxxx"
--header "merchant_key: xxxxxxxxxxx"
"street_name":"John Street",
"city":"San Francisco",

Payment and pre-authorization effectuation services parameters#


card Card data
numberCustomer's card number (PAN).< 19 NYes
barcode_dataContains 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 ANNo
idCode 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 ANNo
security_codeCard security code.< 4 NNo
expiry_dateCard expiry date in MMYY format.4 NNo
issue_numberCredit card's issue number.< 3 NNo
issue_dateCredit card's issue date in MMYY format.< 4 ANo
Card encryption data
typeIdentifies 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 NNo
Card EMV chip Data
dataThis field holds the EMV tags of transactions using an EMV chip.< 510 ANNo
track_1 ou track_2Track 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 ANNo
acquirer Acquirer data
aciThe 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 ANNo
input_typeIndicates 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 AYes
cash_back_amountCash back amount (in cents)< 12 NNo
reference_numberThis 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 ANNo
operator_codeUser name of the person running the application that is submitting the transaction.< 25 ANo
soft_descriptor_2This field is used to replace the City/State section of the Merchant Descriptor on the cardholder statement.< 40 ANo
terminal Terminal data
chip_conditionsThis 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 NNo
authentication Authentication data
PIN authentication data
valueEncrypted PIN. Mandatory when the cardholder types the password online.< 64 ANNo
PIN authentication encryption data
ksnPIN encryption KSN. Mandatory when the cardholder types the password online.< 20 ANNo

barcode_data field details#

- 000 = PAN - No encryption
- 001 = Visa - TLV - No encryption
4-NVariableANSBar code data

Payment service request example#

To use this example, don't forget to define the variable {{url}} with the value

--request POST "https://esitef-homologacao.softwareexpress.com.br/e-sitef-hml/api/v1/payments/1234567890abcdefghijklmnopqrstuvw
--header "Content-Type: application/json"
--header "merchant_id: xxxxxxxx"
--header "merchant_key: xxxxxxxxxxx"

Response Parameters#

balanceCurrent balance after payments with voucher cards (in cents).< 12 N
avs_resultAddress Verification System response for the requested transaction.1 A
authorization_numberAuthorization number.< 6 AN
cvv2_responseCVV2 response for the requested transaction.1 A
emv_dataEMV data< 510 AN
tidEPX transaction ID.< 20 AN
authorizer_response_codeEPX response code.< 3 AN
authorizer_response_messageEPX response message.< 80 AN
authorizer_datePayment authorization date returned by the authorizer in DD/MM/AAAA'T'HH:mm. Example: 13/07/2017T16:0316 AN

Payment service response example#

"code": "0",
"message": "OK. Transaction successful.",
"payment": {
"authorizer_code": "00",
"authorizer_message": "EXACT MATCH",
"status": "CON",
"nit": "77866520f106682a128d0e2f8ef4c92517c043fa98e3a77a1ffd37ae884ebc47",
"order_id": "02061433035",
"customer_receipt": "===== RECEIPT= ====",
"merchant_receipt": "===== RECEIPT= ====",
"authorizer_id": "1",
"acquirer_id": "0",
"acquirer_name": "EPX",
"authorizer_date": "02/01/2019T18:15",
"authorization_number": "053130",
"merchant_usn": "2061433036",
"esitef_usn": "190102021262100",
"tid": "09KGH48QH799RU2QY3V",
"amount": "10000",
"payment_type": "C",
"authorizer_merchant_id": "700010",
"avs_result": "Y",
"payment_date": "02/01/2019T18:15"