EPX

The merchant can configure e-SiTef transactions to be routed by several payment providers. One of them is EPX.

Supported e-SiTef 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 e-SiTef'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

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