Fepas HUB

The merchant can configure Online Payment transactions to be routed by several payment providers. One of them is FEPAS HUB.

The objective of this document is to describe the required configurations on Online Payment to enable transactions to be routed by FEPAS HUB.

ATTENTION: This routing is only for contactless transport transactions.

Online Payment Interfaces Supported for Integration#

You can use the following interfaces for integration with Fepas HUB routing:

  • REST Payment
  • REST Cancel
  • REST Pre Authorization
  • REST Logon
  • REST Table Load

ATTENTION:The schedule feature is not supported by this integration.

REST Payment#

The following fields are complementary to the existing fields mentioned in the documentation Payment effectuation service.

REST Payment Effectuation#

Payment Request#

ParameterDescriptionFormatRequired
resubmission_idID for resubmitting a previously denied payment in certain cases as allowed by the issuer.= 16 NCond.
acquirer_idRouting code to be used on the transaction.

It can assume the values listed in the Routing Codes table.

If this field is not sent, the authorizer configuration will be used to define the routing.
< 4 NNO
original_authorization_numberOriginal transaction authorization number.<6 ANCond.
authorizer_macMAC of the purchase transaction (all brands) 4 positions ASCII Merchant Advice Code (MAC).< 4 ANCond.
authorization_terminalAttribute of type authorization_terminal
authenticationAttribute of type authentication
terminalAttribute of type terminal
cardAttribute of type card
mttAttribute of type mtt

Payment Request Example#

To use this example, don't forget to define the variable {{url}} with the value
esitef-homologacao.softwareexpress.com.br

curl
--request POST "https://esitef-homologacao.softwareexpress.com.br/e-sitef-hml/api/v1/payments/1234567890abcdefghijklmnopqrstuvwxyz1234567890abcdefghijklmnopqr"
--header "Content-Type: application/json"
--header "merchant_id: xxxxxxxx"
--header "merchant_key: xxxxxxxxxxx"
--data-binary
{
"card":{
"expiry_date":"1222",
"crypto":{
"ksn":"xxxxxxxxxxx"
},
"track_2":"****************************************",
"pos_entry_mode":{
"value":"07",
"pin_capability":"2"
},
"emv":{
"card_sequence_number":"xxxxxx",
"data":"820258009F2701809F2608B42433F98916B3319F36020074"
}
},
"terminal":{
"id":"SE111111",
"type":"2",
"input_mode":"5",
"pin_pad_physical_features":"6",
"handling_type":"1",
"reader_capabilities":"7"
},
"mtt": {
"id": "1",
"first_journey_date": "0925",
"vehicle_id": "012345678901234567",
"gps_location": "050.167958;-097.133000"
},
"resubmission_id": "0123456789012345"
}
--verbose

Payment Response#

ParameterDescriptionFormat
resubmission_idID used for resubmitting in case of denied payment.= 16 N
paymentAttribute of type payment
cardAttribute of type resp_card

Payment Response Example#

{
"code":"0",
"message":"OK. Transaction successful."
"payment":{
"authorizer_code":"000",
"authorizer_message":"Transacao OK",
"status":"CON",
"nit":"1234567890abcdefghijklmnopqrstuvwxyz1234567890abcdefghijklmnopqr",
"order_id":"13034649671",
"customer_receipt":"====CUPOM COMPRADOR====",
"merchant_receipt":"====CUPOM ESTABELECIMENTO====",
"authorizer_id":"2",
"acquirer_id":"0005",
"acquirer_name":"FEPAS HUB",
"authorizer_date":"07/08/2018T16:52",
"authorization_number":"132030",
"merchant_usn":"13034649671",
"esitef_usn":"170713097340300",
"sitef_usn":"132030",
"host_usn":"999132030",
"tid": "000030000016",
"payment_date":"07/08/2018T16:52",
"amount":"1000",
"payment_type":"C",
"issuer":"2",
"authorizer_merchant_id":"000000000000005",
"acquirer_table_load_required":"0",
"conciliation_authorizer_merchant_id":"6887542",
"authorization_terminal":{
"usn":"555845",
"id":"SE111111"
}
},
"resubmission_id": "0123456789012345"
}

REST Payment Confirmation#

The following fields are complementary to the existing fields mentioned in the documentation Payment confirmation service.

Confirmation Request#

ParameterDescriptionFormatRequired
issuer_scripts_resultsIssuer Scripts Results

Mandatory if the transaction uses an EMV chip.
= N/A ANCond.

Confirmation Request Example#

To use this example, don't forget to define the variable {{url}} with the value
esitef-homologacao.softwareexpress.com.br

curl
--request PUT "https://esitef-homologacao.softwareexpress.com.br/e-sitef-hml/api/v1/payments/1234567890abcdefghijklmnopqrstuvwxyz1234567890abcdefghijklmnopqr?confirm=true&issuer_scripts_results=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
--header "merchant_id:xxxxxxxxxxxxxxx"
--header "merchant_key:xxxxxxxxxxx"
--verbose

Confirmation Response#

No additional parameters are required.

Confirmation Response Example#

{
"code": "0",
"message": "OK. Transaction successful.",
"payment": {
"status": "CON"
}
}

REST Cancellation#

REST Cancel Effectuation#

The following fields are complementary to the existing fields mentioned in the documentation Cancel service.

Cancel Request#

ParameterDescriptionFormatRequired
terminalAttribute of type terminal
cardAttribute of type card
authenticationAttribute of type authentication

Cancel Request Example#

To use this example, don't forget to define the variable {{url}} with the value
esitef-homologacao.softwareexpress.com.br

curl
--request PUT "https://esitef-homologacao.softwareexpress.com.br/e-sitef/api/v1/cancellations/1234567890abcdefghijklmnopqrstuvwxyz1234567890abcdefghijklmnopqr"
--header "Content-Type: application/json"
--header "merchant_id: xxxxxxxx"
--header "merchant_key: xxxxxxxxxxx"
--data-binary
{
"card":{
"crypto":{
"ksn":"xxxxxxxxxxx"
},
"pos_entry_mode":{
"value":"81",
"pin_capability":"1"
},
"track_2":"****************************************",
"expiry_date":"1222"
},
"terminal":{
"id":"SE111111",
"type":"0",
"input_mode":"5",
"pin_pad_physical_features":"3",
"handling_type":"1",
"reader_capabilities":"4",
"chip_conditions":"2"
},
"authentication":{
"pin":{
"crypto":{
"type":"002"
}
}
},
"amount":"1500"
}
--verbose

Cancel Response#

ParameterDescriptionFormatRequired
cancellation Attribute of type cancellation

Cancel Response Example#

{
"code": "0",
"message": "OK. Transaction successful.",
"cancellation": {
"authorizer_code": "00",
"authorizer_message": "Sucesso",
"status": "CON",
"nit": "10f53cd3dab3222e5e37b725dfe368331958866a2d07c4ba7f382a8c5f42fd9e",
"order_id": "03110843259",
"customer_receipt": "=== RECIBO DE CANCELAMENTO ===",
"authorizer_id": "2",
"acquirer_id": "412",
"acquirer_name": "FEPAS HUB",
"authorizer_date": "03/09/2018T11:09",
"authorization_number": "030020",
"merchant_usn": "3110843259",
"esitef_usn": "180903014387861",
"sitef_usn": "000060",
"host_usn": "999030021",
"tid": "000030000014",
"amount": "1500",
"payment_type": "C",
"authorizer_merchant_id": "000000000100250",
"conciliation_authorizer_merchant_id": "000000000100250",
"authorization_terminal": {
"usn": "030021",
"id": "F1000001"
},
"esitef_date": "03/09/2018T11:09",
"is_host_cancel": "false"
}
}

REST Pre-Authorization#

The following fields are complementary to the existing fields mentioned in the documentation Pre-Authorization effectuation service.

REST Pre-Authorization Effectuation#

Pre-Authorization Request#

ParameterDescriptionFormatRequired
resubmission_idID for resubmitting a previously denied payment in certain cases as allowed by the issuer.= 16 NCond.
acquirer_idRouting code to be used on the transaction.

It can assume the values listed in the Routing Codes table.

If this field is not sent, the authorizer configuration will be used to define the routing.
< 4 NNO
authenticationAttribute of type authentication
terminalAttribute of type terminal
cardAttribute of type card
mttAttribute of type mtt

Pre-Authorization Request Example#

To use this example, don't forget to define the variable {{url}} with the value
esitef-homologacao.softwareexpress.com.br

curl
--request POST "https://esitef-homologacao.softwareexpress.com.br/e-sitef-hml/api/v1/preauthorizations/1234567890abcdefghijklmnopqrstuvwxyz1234567890abcdefghijklmnopqr"
--header "Content-Type: application/json"
--header "merchant_id: xxxxxxxx"
--header "merchant_key: xxxxxxxxxxx"
--data-binary
{
"card":{
"expiry_date":"1222",
"crypto":{
"ksn":"xxxxxxxxxxx"
},
"track_2":"****************************************",
"pos_entry_mode":{
"value":"07",
"pin_capability":"2"
},
"emv":{
"card_sequence_number":"xxxxxx",
"data":"820258009F2701809F2608B42433F98916B3319F36020074"
}
},
"terminal":{
"id":"SE111111",
"type":"2",
"input_mode":"5",
"pin_pad_physical_features":"6",
"handling_type":"1",
"reader_capabilities":"7"
},
"mtt": {
"id": "1",
"first_journey_date": "0925",
"vehicle_id": "012345678901234567",
"gps_location": "050.167958;-097.133000"
},
"resubmission_id": "0123456789012345"
}
--verbose

Pre-Authorization Response#

ParameterDescriptionFormato
resubmission_idID used for resubmitting in case of denied payment.= 16 N
pre_authorizationAttribute of type pre_authorization
cardAttribute of type resp_card

Pre-Authorization Response Example#

{
"code":"0",
"message":"OK. Transaction successful.",
"pre_authorization":{
"authorizer_code":"000",
"authorizer_message":"Transacao OK",
"status":"CON",
"nit":"1234567890abcdefghijklmnopqrstuvwxyz1234567890abcdefghijklmnopqr",
"customer_receipt":"====CUPOM COMPRADOR====",
"merchant_receipt":"====CUPOM ESTABELECIMENTO====",
"authorizer_id":"2",
"order_id":"13034649671",
"acquirer_name":"FEPAS HUB",
"acquirer_id":"0005",
"authorization_number":"132030",
"merchant_usn":"13034649671",
"authorizer_date":"07/08/2018T16:52",
"esitef_usn":"170713097340300",
"sitef_usn":"132030",
"host_usn":"999132030",
"amount":"1000",
"tid": "000030000016",
"issuer":"2",
"payment_type":"C",
"authorizer_merchant_id":"000000000000005",
"acquirer_table_load_required":"0",
"conciliation_authorizer_merchant_id":"6887542",
"authorization_terminal":{
"usn":"555845",
"id":"SE111111"
}
},
"resubmission_id": "0123456789012345"
}

REST Pre-Authorization Capture#

The following fields are complementary to the existing fields mentioned in the documentation Pre-Authorization Capture Service.

Pre-Authorization Capture Request Example#

To use this example, don't forget to define the variable {{url}} with the value
esitef-homologacao.softwareexpress.com.br

curl
--request POST "https://esitef-homologacao.softwareexpress.com.br/e-sitef-hml/api/v1/preauthorizations/capture/1234567890abcdefghijklmnopqrstuvwxyz1234567890abcdefghijklmnopqr"
--header "merchant_id:xxxxxxxxxxxxxxx"
--header "merchant_key:xxxxxxxxxxx"
--data-binary
{
"card":{
"expiry_date":"1222",
"crypto":{
"ksn":"xxxxxxxxxxx"
},
"track_2":"****************************************",
"pos_entry_mode":{
"value":"07",
"pin_capability":"2"
},
"emv":{
"card_sequence_number":"xxxxxx",
"data":"820258009F2701809F2608B42433F98916B3319F36020074"
}
},
"terminal":{
"id":"SE111111",
"type":"2",
"input_mode":"5",
"pin_pad_physical_features":"6",
"handling_type":"1",
"reader_capabilities":"7"
}
--verbose

Pre-Authorization Captura Response#

No additional parameters are required.

Pre-Authorization Captura Response Example#

{
"code": "0",
"message": "OK. Transaction successful.",
"capture": {
"authorizer_code":"000",
"authorizer_message":"Transacao OK",
"status":"CON",
"nit":"1234567890abcdefghijklmnopqrstuvwxyz1234567890abcdefghijklmnopqr",
"customer_receipt":"====CUPOM COMPRADOR====",
"merchant_receipt":"====CUPOM ESTABELECIMENTO====",
"authorizer_id":"2",
"order_id":"13034649671",
"acquirer_name":"FEPAS HUB",
"acquirer_id":"0005",
"authorization_number":"132030",
"merchant_usn":"13034649671",
"authorizer_date":"07/08/2018T16:52",
"esitef_usn":"170713097340300",
"sitef_usn":"132030",
"host_usn":"999132030",
"amount":"1000",
"issuer":"2",
"payment_type":"C",
"authorizer_merchant_id":"000000000000005"
}
}

Logon REST#

The logon is a new and an exclusive feature of the Online Payment FEPAS routing.

If the request version field is different from the response acquirer_table_load.version field, it is necessary to do a table load.

Logon Request#

ParameterDescriptionFormatRequired
authorizer_idAuthorizer code.< 4 NYES
acquirer_idRouting code to be used on the transaction.

It can assume the values listed in the Routing codes table.
< 4 NNO
versionIt is the version of the parameters table related to an Authorizer. Each Authorizer may have a distinct version of those parameters.

Attention: If the Merchant does not have any table to the informed Authorizer, this field must contain only zeroes.
< 8 NYES
terminalAttribute of type terminal

NOTE: Just the id attribute is required in the terminal attribute during the Logon.

Logon Request Example#

To use this example, don't forget to define the variable {{url}} with the value
esitef-homologacao.softwareexpress.com.br

curl
--request POST "https://esitef-homologacao.softwareexpress.com.br/e-sitef/api/v1/acquirer_tables"
--header "Content-Type: application/json"
--header "merchant_id: xxxxxxxx"
--header "merchant_key: xxxxxxxxxxx"
--data-binary
{
"authorizer_id":"2",
"version":"4",
"terminal": {
"id":"ES000001"
}
}
--verbose

Logon Response#

ParameterDescriptionFormat
codeOnline Payment response code. Any code different from ‘0’ represents a failure. To find more information, check the API Codes section.< 4 N
messageOnline Payment response message.< 500 AN
acquirer_table Attribute of type acquirer_table

Logon Response Example#

{
"code": "0",
"message": "OK. Transaction successful.",
"acquirer_table": {
"code": "00",
"message": "Sucesso",
"acquirer_id": "5",
"acquirer_name": "Redecard",
"usn": "000230",
"merchant_code": "000000000100250",
"version": "40361885",
"signature": "R8yxlnT24sSm1Zt77Jj44pohO8LapTNjWt1nqV8zGKg=",
"date": "06/09/2018T11:32:31"
}
}

REST Table Load#

The table load is a new and an exclusive feature of the Online Payment FEPAS routing. This request can be made successfully only after a logon and will reuse the information returned by it (for instance, acquirer_table_load.usn, authorizer_id, version and terminal.id).

Table Load Request#

ParameterDescriptionFormatRequired
authorizer_idAuthorizer code.

It must have the same value as the one informed at the logon request.
< 4 NYES
acquirer_idRouting code to be used on the transaction.

It can assume the values listed in the Routing Codes table.

If this field is not sent, the authorizer configuration will be used to define the routing.
< 4 NNO
versionIt is the version of the parameters table related to an Authorizer. Each Authorizer may have a distinct version of those parameters.

It must have the same value as the one informed at the Logon request.

NOTE: If the Merchant does not have any table to the informed Authorizer, this field must contain only zeroes.
< 4 NYES
terminalAttribute of type terminal

NOTE: Just the id attribute is required in the terminal attribute during the Tables load.

Table Load Request Example#

To use this example, don't forget to define the variable {{url}} with the value
esitef-homologacao.softwareexpress.com.br

curl
--request PUT "https://esitef-homologacao.softwareexpress.com.br/e-sitef/api/v1/acquirer_tables/<acquirer_table.usn value>"
--header "Content-Type: application/json"
--header "merchant_id: xxxxxxxx"
--header "merchant_key: xxxxxxxxxxx"
--data-binary
{
"authorizer_id":"2",
"version":"4",
"terminal": {
"id":"ES000001"
}
}
--verbose

Table Load Response#

ParameterDescriptionFormat
codeOnline Payment response code. Any code different from ‘0’ represents a failure. To find more information, check the API Codes section.< 4 N
messageOnline Payment response message.< 500 AN
acquirer_tableAttribute of type acquirer_table

Table Load Response Example#

{
"code": "0",
"message": "OK. Transaction successful.",
"acquirer_table": {
"code": "00",
"message": "Sucesso",
"acquirer_id": "5",
"acquirer_name": "Redecard",
"usn": "000230",
"merchant_code": "000000000100250",
"version": "40361885",
"signature": "R8yxlnT24sSm1Zt77Jj44pohO8LapTNjWt1nqV8zGKg=",
"date": "06/09/2018T11:41:49",
"credit_bins": [
{
"bin": {
"start": "549202000",
"end": "549202999"
},
"brand_code": "005",
"is_voucher": "N",
"features": "24",
"subtype": "00"
},
{
"bin": {
"start": "549221000",
"end": "549221999"
},
"brand_code": "005",
"is_voucher": "N",
"features": "24",
"subtype": "00"
}
],
"public_keys": [
{
"rid": "A000000004",
"certification_authority_public_key_index": "F3",
"certification_authority_public_key_exponent_size": "1",
"certification_authority_public_key_exponent": "03",
"certification_authority_public_key_modulus_size": "144",
"certification_authority_public_key_modulus": "98F0C770F23864C2E",
"checksum_status": "1",
"certification_authority_public_key_checksum": "FCB86DA7076023DB8F38D992680175A839FFC9A6"
},
{
"rid": "A000000004",
"certification_authority_public_key_index": "F1",
"certification_authority_public_key_exponent_size": "1",
"certification_authority_public_key_exponent": "03",
"certification_authority_public_key_modulus_size": "176",
"certification_authority_public_key_modulus": "A0DCF4BDE19C3546B4B",
"checksum_status": "1",
"certification_authority_public_key_checksum": "55CD192717EE59A8E80A2B2D77528F6552F23BBE"
}
],
"emv_params": [
{
"aid_code": "01",
"aid_length": "07",
"aid": "A0000000041010 ",
"application_type": "01",
"application_name": " ",
"default_value": "03",
"version_opt1": "0002",
"version_opt2": "0002",
"version_opt3": "0002",
"terminal_country_code": "076",
"transaction_currency_code": "986",
"transaction_currency_exponent": "2",
"merchant_id": "000000000100250",
"merchant_category_code": "0000",
"terminal_id": "00000000",
"terminal_capabilities": "E0F0C8",
"terminal_capabilities_additional": "FF80B0F001",
"terminal_type": "22",
"terminal_action_code_default": "FE50BCA000",
"terminal_action_code_denial": "0000000000",
"terminal_action_code_online": "FE50BCF800",
"terminal_floor_limit": "00000000",
"transaction_category_code": "R",
"tdol": "9F02065F2A029A039C0195059F37040000000000",
"ddol": "9F37040000000000000000000000000000000000",
"authorization_response_code_offline_approved": "Y1",
"authorization_response_code_offline_declined": "Z1",
"authorization_response_code_unable_online_offline_approved": "Y3",
"authorization_response_code_unable_online_offline_declined": "Z3",
"contactless_zero_amount": "1",
"contactless_mode": "4",
"contactless_transaction_limit": "05F5E0FF",
"contactless_floor_limit": "00000000",
"contactless_cvm_limit": "00001389",
"contactless_application_version": "0000",
"contactless_selection_mode": "1",
"contactless_terminal_action_code_default": "FC509C8800",
"contactless_terminal_action_code_denied": "0000000000",
"contactless_terminal_action_code_online": "FC509C8800"
},
{
"aid_code": "02",
"aid_length": "07",
"aid": "A0000000043060 ",
"application_type": "02",
"application_name": " ",
"default_value": "03",
"version_opt1": "0002",
"version_opt2": "0002",
"version_opt3": "0002",
"terminal_country_code": "076",
"transaction_currency_code": "986",
"transaction_currency_exponent": "2",
"merchant_id": "000000000100250",
"merchant_category_code": "0000",
"terminal_id": "00000000",
"terminal_capabilities": "E0D0C8",
"terminal_capabilities_additional": "FF80B0F001",
"terminal_type": "22",
"terminal_action_code_default": "FE50BCA000",
"terminal_action_code_denial": "0000000000",
"terminal_action_code_online": "FE50BCF800",
"terminal_floor_limit": "00000000",
"transaction_category_code": "R",
"tdol": "9F02065F2A029A039C0195059F37040000000000",
"ddol": "9F37040000000000000000000000000000000000",
"authorization_response_code_offline_approved": "Y1",
"authorization_response_code_offline_declined": "Z1",
"authorization_response_code_unable_online_offline_approved": "Y3",
"authorization_response_code_unable_online_offline_declined": "Z3",
"contactless_zero_amount": "1",
"contactless_mode": "4",
"contactless_transaction_limit": "05F5E0FF",
"contactless_floor_limit": "00000000",
"contactless_cvm_limit": "00001389",
"contactless_application_version": "0000",
"contactless_selection_mode": "1",
"contactless_terminal_action_code_default": "FC501C8800",
"contactless_terminal_action_code_denied": "0000800000",
"contactless_terminal_action_code_online": "FC501C8800"
}
],
"emv_tags": [
{
"aid_code": "46",
"all_emv_tags": "9f269f109f379f36959c9f025f2a829f1a9f03"
},
{
"aid_code": "45",
"all_emv_tags": "9f269f109f379f36959c9f025f2a829f1a9f03"
}
],
"mandatory_emv_tags": [
{
"aid_code": "46",
"mandatory_emv_tags": "9f269f109f379f36959c9f025f2a829f1a9f03"
},
{
"aid_code": "45",
"mandatory_emv_tags": "9f269f109f379f36959c9f025f2a829f1a9f03"
}
],
"optional_emv_tags": [
{
"aid_code": "46",
"optional_emv_tags": "5f3484"
},
{
"aid_code": "45",
"optional_emv_tags": "5f3484"
}
],
"brand_per_credit_aid": [
{
"aid_code": "01",
"brand_code": "002"
},
{
"aid_code": "01",
"brand_code": "004"
}
],
"brand_per_debit_aid": [
{
"aid_code": "02",
"brand_code": "002"
},
{
"aid_code": "02",
"brand_code": "005"
}
]
}
}

Data Types#

authorization_terminal#

ParameterDescriptionFormatRequired
usnNSU of the Authorization Terminal of the original transaction= 6 NCond.
local_date_timeLocal date and time of the original transaction ('MMddHHmmss' format)= 10 NCond.

authentication#

ParameterDescriptionFormatRequired
pin Attribute of type authentication.pin

authentication.pin#

ParameterDescriptionFormatRequired
valueEncrypted PIN.

Mandatory when the cardholder types the password online.
< 16 ANCond.
cryptoAttribute of type pin.crypto

pin.crypto#

ParameterDescriptionFormatRequired
typePIN encryption process.

It can assume the values listed in the PIN Encryption Process Codes table.
This field is mandatory only when the PIN is sent.
= 3 NCond.
ksnPIN encryption KSN.

Mandatory when the cardholder types the password online.
< 20 ANCond.

terminal#

ParameterDescriptionFormatRequired
idTerminal ID.< 8 ANSIM
typeTerminal Attendance Type.

It can assume the values listed in the Terminal Attendance Type Codes table.
= 1 NSIM
input_modeTerminal input capability.

It can assume the values listed in the Terminal Input Capability Codes table.
= 2 NSIM
pin_pad_physical_featuresPIN-pad physical features.

It can assume the values listed in the PIN-pad Physical Feature Codes table.
= 1 NSIM
handling_typePassword handling type.

It can assume the values listed in the Password Handling Type Codes table.
= 1 NSIM
reader_capabilitiesReader capabilities.

It can assume the values listed in the Card Reader Capability Codes table.
= 1 NSIM
chip_conditionsCHIP conditions.

It can assume the values listed in the CHIP Condition Codes table.
= 1 NSIM

card#

ParameterDescriptionFormatRequired
service_codeThis field has 3 digits and those three digits appear after the track 2 expiry date, according to the ISO/IEC 7813 standards.

Track 2 example:
;1234567890123445=99011200XXXX00000000?*
Service Code: 120.
= 3 NCond.
binThe card BIN field must be sent when the transaction is typed or made by either track or chip.
This field has 6 digits and those 6 digits appear after the track 2 starting sentinel, according to the ISO/IEC 7813 standards.

Track 2 example:
;1234567890123445=99011200XXXX00000000?*
Card BIN: 123456.
= 6 NCond.
last4Credit card last four digits must be sent when the transaction is typed or made by either track or chip.
Those four digits appear before the track 2 separator (“=”), according to the ISO/IEC 7813 standards.

Track 2 example:
;1234567890123445=99011200XXXX00000000?*
Last four digits: 3445.
= 6 NCond.
track_1Track 1, encrypted according to the rules established between the Merchant and Software Express.

This field is mandatory if the Track 1 is sent.
AN N/ACond.
track_2Credit card Track 2 or client identification.

The Track 2 is encrypted by hardware according to the rules established between the Merchant and Software Express.

This field is mandatory if the Track 2 is sent.
< 99Cond.
subtypeCredit card subtype.

It can assume the values listed in the Subtype Codes table.

Mandatory if the transaction is made with a voucher.
= 2 ANCond.
cryptoAttribute of type card.crypto
pinAttribute of type card.pin
pos_entry_modeAttribute of type pos_entry_mode
emvAttribute of type emv
numberCard number (PAN).

Used in the service(s):
Cancel
LLvar n..99 NCond.
expiry_dateCard expiry date.

Used in the service(s):
Cancel
= 4 NCond.
security_codeCard security code.

Used in the service(s):
Cancel
= 6 NCond.

card.crypto#

ParameterDescriptionFormatRequired
ksnKSN (Key Serial Number) of the PAN encryption and track 2 (field card.track_2). Used in DUKPT cryptography.
Mandatory when PAN/track 2 encryption type DUKPT (004) is used. If absent the PAN encryption type 3DES (002) is assumed.
= 20 ANCOND
ksn_trac_1KSN (Key Serial Number) of the track 1 encryption (filed card.track_1). Used in DUKPT cryptography.
Mandatory when track 1 encryption type DUKPT (004) is used. If absent the PAN encryption type 3DES (002) is assumed.
= 20 ANCOND

card.pin#

ParameterDescriptionFormatRequired
valueEncrypted PIN.

Mandatory when the cardholder types the password online.
< 64Cond.

resp_card#

ParameterDescriptionFormat
tokenCarat Online Payment stored card HASH. It is forbidden to send an AN open card number (‘number’ field) and a stored card (‘token’ field) in the same request.= 88 AN
parPAR (Payment Account Reference).= 29 AN

pos_entry_mode#

ParameterDescriptionFormatRequired
valueCard input mode.

It can assume the values listed in the Card Input Mode Codes table.
= 2 NYES
pin_capabilityTerminal PIN input capabilities.

It can assume the values listed in the Terminal PIN Input Capability Codes table.
= 1 NYES

emv#

ParameterDescriptionFormatRequired
card_sequence_numberCard sequence number of the EMV card used (tag 5F34).
This field is mandatory only when the transaction uses an EMV chip and the card informs this data..
< 3 NCond.
dataThis field holds the EMV tags of transactions using an EMV chip. Its contents are sent in ASCII bytes, in the following TLV format: type, length, content. For example, if we were to send:

Tag: 82 - (Application Interchange Profile), length: 2, content: 5800;
Tag: 9F27 - (Cryptogram Information Data), length: 1, content: 80;
Tag: 9F26 - (Application Cryptogram), length: 8, content b42433f98916b331.

The resulting value would be:
"data":"820258009F2701809F2608B42433F98916B331".

This field is mandatory if the transaction uses an EMV chip.
< 999 N/ACond.

mtt#

ParameterDescriptionFormatRequired
idMTT transaction ID (Mass Transport Transaction). Informs the type of the requested transaction.

It can assume the values listed in the MTT transaction ID Codes table.
= 1 NCond.
first_journey_dateMTT transaction first journey date, following the MMDD format.= 4 NCond.
vehicle_idVehicle identification. Mandatory for MTT= 18 NNO
gps_locationGPS Location, must be sent in MTT transactions with the vehicle location in decimal latitude and longitude, for example:
050.167958;-097.133000
(xxx.nnnnnn;-xxx.nnnnnn), where is:
“xxx” – Degree matches;
“.” – Degree and Minutes Separator;
“nnnnnn” – Minutes converted to fraction of degrees;
“;” – Latitude and Longitude separator;
“-“ – Indication of negative degrees.
< 24 ANNO
transport_mode_indicatorTransport mode indicator. Required for MTT. Transport Mode Indicator table< = 2 NNO

payment#

ParameterDescriptionFormat
acquirer_table_load_requiredThis field shows whether an Authorizer table load must be done or not.

0 - Parameters are up-to-date.
1 - The parameters are outdated – the Merchant must do a Table Load.
= 1 N
conciliation_authorizer_merchant_idSale establishment code.= 15
authorization_terminalAttribute of type authorization_terminal

pre_authorization#

ParameterDescriptionFormat
acquirer_table_load_requiredThis field shows whether an Authorizer table load must be done or not.

0 - Parameters are up-to-date.
1 - The parameters are outdated – the Merchant must do a Table Load.
= 1 N
conciliation_authorizer_merchant_idSale establishment code.= 15
authorization_terminalAttribute of type authorization_terminal

cancellation#

ParameterDescriptionFormat
acquirer_table_load_requiredInforms if the Merchant need to do a table load along with an Authorizer.

0 - Parameters are up-to-date.
1 - ‘1’ – Parameters are outdated – the Merchant must do a Table Load.
= 1 N
conciliation_authorizer_merchant_idCódigo de Estabelecimento da Venda.= 15 N
authorization_terminalAttribute of type authorization_terminal

authorization_terminal#

ParameterDescriptionFormat
usnAuthorization terminal USN.= 6 N
idAuthorization terminal ID.= 8 AN

acquirer_table#

ParameterDescriptionFormat
codeFEPAS operation response code.= 2 AN
messageFEPAS response message.< 999 AN
usnOperation USN.= 6 N
dateLocal date and time.= 19 N
authorizer_idAuthorizer code.< 4 N
merchant_codeMerchant code.< 15 AN
versionIt is the version of the parameters table related to an Authorizer. Each Authorizer may have a distinct version of those parameters. Attention: If the Merchant does not have any table to the informed Authorizer, this field must contain only zeroes.< 8 N
signatureParametrization signature.< 999 AN
acquirer_idAcquirer code.

Returns in the service(s):
Table Load
< 4 N
acquirer_nameAcquirer name.

Returns in the service(s):
Table Load
N/A AN
credit_bins[]Attribute of type product_bins

Returns in the service(s):
Table Load
debit_bins[]Attribute of type product_bins

Returns in the service(s):
Table Load
emv_params[]Attribute of type emv_params

Returns in the service(s):
Table Load
public_keys[]Attribute of type public_keys

Returns in the service(s):
Table Load
mandatory_emv_tags[]Attribute of type mandatory_emv_tags

Returns in the service(s):
Table Load
optional_emv_tags[]Attribute of type optional_emv_tags

Returns in the service(s):
Table Load
emv_tags[]Attribute of type emv_tags

Returns in the service(s):
Table Load
brand_per_credit_aid[]Attribute of type brand_per_x_aid

Returns in the service(s):
Table Load
brand_per_debit_aid[]Attribute of type brand_per_x_aid

Returns in the service(s):
Table Load

product_bins#

ParameterDescriptionFormat
brand_codeCard brand code.

It can assume the values listed in the Brand Codes table.
= 2 AN
is_voucherIdentifies if the card is a voucher.

Allowed values:
S - Yes
N - No
= 1 AN
featuresBits map composed by 1 binary byte (2 ASCII hexadecimal characters) that indicates the transaction input features.

The 8 th position is the most significant bit and each bit represents a different feature. If a bit is equals 1, the feature is present; if it is 0, the feature is absent.

Bit order: 87654321.

The list of bits can be found in the Features Map.
= 2 AN
subtypeCard subtype.

It can assume the values listed in the SubType Codes table.
= 2 AN
binAttribute of type bin

bin#

ParameterDescriptionFormat
startRange starting BIN.= 9 N
endRange ending BIN. This field has the same individual BIN validation as the previous field.= 9 N

emv_params#

ParameterDescriptionFormat
aid_codeAID code.= 2 N
aid_lengthAID length in bytes (from 05 to 16).= 2 N
aidAID – Application Identifier.= 32 H
application_typeApplication type.

Allowed values:
01 - Credit
02 - Debit
= 2 N
application_nameApplication default tag.= 61 AN
default_valueApplication default value. 03 - EMV.= 2 N
version_opt_1Application Version Number (Terminal) – option #1.= 4 h
version_opt_2Application Version Number (Terminal) – option #2.= 4 h
version_opt_3Application Version Number (Terminal) – option #3.= 4 h
terminal_country_codeTerminal Country Code.= 3 N
transaction_currency_codeTransaction Currency Code.= 3 N
transaction_currency_exponentTransaction Currency Exponent.= 1 N
merchant_idMerchant Identifier.= 15 AN
merchant_category_codeMerchant Category Code.= 4 N
terminal_idTerminal Identification.= 8 AN
terminal_capabilitiesTerminal Capabilities.

It is the bits map that indicates the terminal capabilities. The format and values can be found in the Terminal Capabilities Map.
= 6 H
terminal_capabilities_additionalAdditional Terminal Capabilities.= 10 H
terminal_typeTerminal Type.

It can assume the values listed in the Terminal Type Codes table.
= 2 N
terminal_action_code_defaultTerminal Action Code - Default.= 10 H
terminal_action_code_denialTerminal Action Code – Denial.= 10 H
terminal_action_code_onlineTerminal Action Code – Online.= 10 H
terminal_floor_limitTerminal Floor Limit.= 8 H
transaction_category_codeTransaction Category Code.= 1 AN
tdolTransaction Category Code. Default Transaction Certificate Data Object List (TDOL) (filled with bytes “00” to the right).= 40 H
ddolDefault Dynamics Data Authentication Data Object List (DDOL) (filled with bytes “00” to the right).= 40 H
authorization
_response_code
_offline_approved
Authorization Response Code - offline approved.= 2 AN
authorization
_response_code
_offline_declined
Authorization Response Code - offline declined.= 2 AN
authorization
_response_code
_unable_online_offline_approved
Authorization Response Code - unable to go online - offline approved.= 2 AN
authorization
_response_code
_unable_online_offline_declined
Authorization Response Code - unable to go online - offline declined.= 2 AN
contactless_zero_amountInforms if the contactless chip supports zero amount transactions.

Allowed values:
0 - Does not support.
1 - Supports, but only if the transaction is online.
= 1 N
contactless_modeTerminal AID handling capabilities if the card chip is contactless.

It can assume the values listed in the Terminal AID Handling Capabilities Codes table.
= 1 N
contactless_transaction_limitTerminal/Reader Contactless Transaction Limit.= 8 H
contactless_floor_limitTerminal/Reader Contactless Floor Limit.= 8 H
contactless_cvm_limitTerminal/Reader CVM Required Limit.= 8 H
contactless_application_versionPayPass Mag Stripe Application Version Number (Terminal).= 4 H
contactless_selection_modeInforms the application selection mode to contactless cards.

Allowed values:
0 - The application is selected automatically according to a priority list.
1 -A selection menu will be presented if there is any other compatible application.
= 1 N
contactless
_terminal_action
_code_default
Terminal Action Code – Default (for contactless cards).= 10 H
contactless
_terminal_action
_code_denied
Terminal Action Code – Denied (for contactless cards).= 10 H
contactless
_terminal_action
_code_online
Terminal Action Code – Online (for contactless cards).= 10 H

public_keys#

ParameterDescriptionFormat
ridRID - Registered Application Provider Identifier.= 10 H
certification_authority
_public_key_index
Certification Authority Public Key Index.= 2 H
certification_authority
_public_key_exponent_size
Certification Authority Public Key Exponent (1 ou 3) length in bytes.= 1 N
certification_authority
_public_key_exponent
Certification Authority Public Key Exponent (left aligned).= 6 H
certification_authority
_public_key_modulus_size
Certification Authority Public Key Modulus (until 248)length in bytes.= 3 N
certification_authority
_public_key_modulus
Certification Authority Public Key Modulus (left aligned).= 496 H
checksum_statusStatus do Check Sum (Hash SHA-1).

Allowed values:
0 - Not used.
1 - Present.
= 1 N
certification_authority
_public_key_checksum
Certification Authority Public Key Check Sum (Hash SHA-1).= 40 h

mandatory_emv_tags#

ParameterDescriptionFormat
aid_codeAID code.= 2 N
mandatory_emv_tagsMandatory EMV tags list. Those tags must be sent in the request messages or in the advice transactions EMV data of a complete EMV flow, both online and offline, after the First Generate AC.

Example: 9F269F27959F10.
N/A AN

optional_emv_tags#

ParameterDescriptionFormat
aid_codeAID code.= 2 N
optional_emv_tagsOptional EMV tags list. Those tags can be sent in the request messages or in the advice transactions EMV data of a complete EMV flow, both online and offline, after the First Generate AC.N/A AN

emv_tags#

ParameterDescriptionFormat
aid_codeAID code.= 2 N
all_emv_tagsBit 55 EMV tags list. Those tags must be sent in the Bit 55 of confirmation messages or in the advice transactions EMV data of a complete EMV flow, both online and offline, after the Second Generate AC.

Example: 9F269F27959F10.
N/A AN

brand_per_x_aid#

ParameterDescriptionFormat
aid_codeAID code.= 2 N
brand_codeBrand code.= 3 N

Tables & Maps#

Routing Codes#

CódigoDescription
2005Rede
2013GoodCard
2047Sorocred
2052Tricard
2054Up Brasil
2072Bigcard
2077Valecard
2094Cabal
2125Cielo
2201VR
2206Global Payments
2265Stone
2309Adiq
5001Alelo

Brand Codes#

CódigoDescription
001Visa
002Mastercard
003Amex
005Hipercard
006Diners
008JCB
012Sorocred
014Policard
016Elo
017Cabal
043Tricard
054Valecard
058VR
065Alelo
158Bigcard
235Up
999Unknown brand

Features Map#

Password collection rule with trail in the Purchase:

  1. Checks if the service code is turned on (bit 8);
  2. If it is, then it uses the service code to determine password collection; or
  3. Otherwise, it uses bit 7 to determine password collection.

Password collection rule with trail in the Cancellation:

  1. Checks if the service code is turned on (bit 8);
  2. If it is, then it uses the service code to determine password collection; or
  3. Otherwise, it uses bit 6 to determine password collection.

Table for Byte 1#

BitDescription
8It allows you to type data.
7Requests the last 4 digits (track).
6Magnetic fallback allowed.
5Enables Typed Fallback.
4Reserved for future use.
3Magnetic transaction requires security code (CVV2/CVC2).
2Request security code (typed).
1Allows non-existent or unreadable CVV.

Table for Byte 2#

BitDescription
8Uses service code to determine if it asks for a password (track).
7Requests password (track).
6Requests password on cancellation (track).
5Requests password (entered).
4Request ID (DNI para Argentina).
3Request plan code.
2Requests type of account (checking or savings).
1Validates card expiration date.

Table for Byte 3#

BitDescription
8Requests security code for magnetic invoice payment (track).
7Requests security code for magnetic invoice payment (track).
6Allows non-existent or illegible security code for invoice payment.
5Process chip on cancellation.
4Processes chip on invoice payment.
3Reserved for future use.
2Reserved for future use.
1Reserved for future use.

Subtype Codes#

CódigoDescription (filled with 00 when card is not debit/voucher)
00Card is not of type Debit/Voucher.
01Debit/Food Voucher.
02Debit/Meal Voucher.
03Debit/Culture Voucher.
04Debit/Fuel Voucher
05Debit/Voucher Benefit
19Debit/Voucher Other (Undefined)
25Debit/PEI (Inmediate Electronic Payments)

Terminal Capabilities Map#

Format:

ABCxxxxx DEFGKxxx HIJMxxxx

PositionDescription
ACard number typed.
BMagnetic card.
CContact chip card.
DOpen PIN chip card verification.
EEncrypted PIN online verification.
FSignature on paper.
GEncrypted PIN chip card verification.
K“No CVM” (without bearer verification) method is allowed.
HSDA – Static Data Authentication – of card with chip.
IDDA - Dynamic Data Authentication – of card with chip.
JCard capture.
MOffline authentication CDA.

Terminal Type Codes#

CodeDescription
21Online.
22Off-line with online capability.
23Only off-line.
24Online, unattended.
25Off-line with online capability, unattended.
26Only off-line, unattended.

Terminal AID Handling Capabilities Codes#

CodeDescription
0No support.
1Supports VISA MSD.
2Supports VISA qVSDC.
3Supports MasterCard PayPass Mag Stripe.
4Supports MasterCard PayPass M/Chip.
5Supports Amex Expresspay Magstripe Mode.
6Supports Amex Expresspay EMV Mode.

PIN Encryption Process Codes#

CodeDescription
0013DES between the Merchant and the Authorizer (bypass Software Express).
0023DES between the Merchant and Software Express. Software Express will do the translation for the Authorizer.
003DUKPT 3DES between the Merchant and the Authorizer (bypass Software Express).
004DUKPT 3DES between Merchant and Software Express. Software Express will do the translation for the Authorizer.

Terminal Attendance Type Codes#

CodeDescription
0Terminal with cashier.
2ATM.

Terminal PIN Input Capability Codes#

CodeDescription
0Undefined.
2No terminal (IVR/Voice).
5Chip reader.

PIN-pad Physical Feature Codes#

Position 1 CodeDescription
1No PIN-pad
3PIN-pad with chip reader.
6PIN-pad with contactless and chip reader.
Position 2 CodeDescrição
0PIN-pad without magnetic reader.
1PIN-pad with magnetic reader.

Password Handling Type Codes#

CodeDescription
1No password.
2Online password.
3Off-line password.

Card Reader Capability Codes#

CodeDescription
4Chip and magnetic stripe reader enabled.
5Contactless and magnetic stripe reader enabled.
6Contactless and chip reader enabled
7Contactless, magnetic stripe and chip reader enabled. PIN- pad with chip reader.

Chip Condition Codes#

CodeDescription
1Track without fallback.
2Track with fallback.

Card Input Mode Codes#

CodeDescription
01Card number manual input (typed).
02Magnetic stripe.
05Chip.
07Contactless chip.
81Magnetic stripe fallback (used when the chip reading fails and the first position of the track service code is equals to 2 or 6, indicating that the transaction was made using a card chip).
89E-commerce.
91Contactless magnetic stripe.

Terminal PIN Input Capabilities Codes#

CodeDescription
0Not applicable.
1PIN input capability is present.
2PIN input capability is absent.

MTT transaction ID Codes#

CodeDescription
1AVR (transaction must come with amount zero).
2MTT credit transaction.
3Debt Recovery (resubmission, necessary sending resubmission_id field)
4E-commerce/MOTO Debt Recovery (for typed transactions).
5Tap Online Debt Recovery (for contactless transactions).
6KFT (Known Fare Transaction – or Known Amount Transaction). This model accepts Credit or Debit transactions.
7Debt Recovery tap online to KFT.
8ATC update (zero value transaction).

Pin Entry Capability Codes#

CodeDescription
0Not applicable
1Has PIN entry capability
2No PIN entry capability

Transport Mode Indicator Table#

CodeDescription
00Unknown
01City Bus
02Long-distance Bus
03Subway
04Collective Train
05Train
06Waterborne vehicle
07Toll
08Parking
09Taxi
10high speed train
11rural bus
12Express train
13Transit vehicle
14Self-drive vehicle
15Training vehicle
16Locomotive
17Motor vehicle
18Trailer
19Regional train
20Transport between city
21Funicular train
22Tram, cableway