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

curl
--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"
--data-binary
{
   "merchant_usn":"2061433036",
   "order_id":"02061433035",
   "installments":"1",
   "installment_type":"4",
   "authorizer_id":"1",
   "amount":"10000",
   "additional_data":{
      "payer":{
         "address":{
            "zip_code":"12345678",
            "street_number":"123",
            "street_name":"John Street",
            "city":"San Francisco",
            "state":"CA"
         },
         "phones":[
            {
               "number":"12345678901",
               "type":"6"
            }
         ]
      }
   }
}
--verbose

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

curl 
--request POST "https://esitef-homologacao.softwareexpress.com.br/e-sitef-hml/api/v1/payments/1234567890abcdefghijklmnopqrstuvw
xyz1234567890abcdefghijklmnopqr"
--header "Content-Type: application/json"
--header "merchant_id: xxxxxxxx"
--header "merchant_key: xxxxxxxxxxx"
--data-binary
{
   "card":{
      "number":"4111111111111111",
      "expiry_date":"1222"
   },
   "acquirer":{
      "input_type":"X"
   }
}
--verbose

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

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

Updated 15 days ago

Supported Carat Portal interfaces

Required credentials

Transaction creation service parameters

Request

Transaction creation service request example

Payment and pre-authorization effectuation services parameters

Request

barcode_data field details

Payment service request example

Response Parameters

Payment service response example

`barcode_data` field details