Bin

This item will display specific characteristics for the Bin via SiTef routing.

REST Payment#

Payment Effectuation#

Below are the parameters with specific data for Bin transactions which the merchant's application can send on the payment effectuation service:

ParameterDescriptionFormatMandatory
external_authentication
ucaf_sliContains the UCAF (Universal Cardholder Authentication Field), which corresponds to SLI's last digit (Security Level Indicator) from Mastercard Secure Code.= 1 NNO
version3DS version (1 or 2).= 1 NNO
reference_idDirectory Server identifier for 3DS 2.0 transactions.< 36 ANNO
tavvDSRP-UCAF tokenized transaction cryptogram.< 40 ANNO
cavvCardholder Authentication Verification Value - Codes that refers to card holder authentication result data.< 40 NNO

Card-On-File Parameters#

Definitions#

The following values are accepted for parameters usagee reason, inside of acquirer.card_on_file:

usageDefinition
firstIndicate the first ocurrency
subsequentIndicate subsequent ocorrences of a recurrency
authorizedTo be used together reason=card parameter indicating that the card holder has authorized the card storage
reasonDefinition
cardholderSubsequent purchases triggered by the cardholder
unscheduledSubsequent purchases without scheduling
recurringScheduled recurrent purchases
installmentInstalment thru recurrency
cardTo be used together usage=authorized parameter indicating that the card holder has authorized the card storage

MIT e CIT#

There are two types of card-on-file transactions: CIT (Cardholder Initiated Transaction) and MIT (Merchant Initiated Transaction)

SiglaDefinition
CITis any transaction where the cardholder is actively participating in the transaction, either at a terminal in-store or through a checkout experience online.
MITis a subsequent transaction with already-stored credentials, for which a cardholder has given prior consent to the merchant to store payment credentials for future use, without his or her active engagement. Such would be the case in the automatic billing for subscription services, to name one example.

Valid combinations#

usagereasonDefinitionMIT/CIT?
authorizedcardIndicates that the cardholder has authorized the storage of the cardCIT
firstunscheduledIndicates a single paymentMIT
firstrecurringIndicates the first the first occurrence of a recurrenceMIT
subsequentrecurringIndicates subsequent occurrences of a recurrenceMIT
subsequentcardholderIndicates a payment made by the user with the card already storedCIT
subsequentunscheduledIndicates a subsequent unscheduled occurrence initiated by the merchantMIT
subsequentinstallmentIndicates installment by recurrenceMIT

Payment - Network Token#

Some card brands have a tokenization solution that offers the storage of cards in safes at the brand itself, in an encrypted form. This brand tokenization is intended to improve the security and quality of the transmitted card information, which leads to possible increases in the conversion of approval by issuing banks.

ParameterDescriptionFormatRequired
card
numberToken generated by the brand (DPAN)≤ 19 NYes
cryptogramCryptogram generated by the brand= 28 AYes for network token payments
wallet_typeField that specifies whether the transaction is processed with PAN or DPAN. You must send the value “network_token” for tokenized transactions.ANYes for network token payments

Request:

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

curl
--request POST "https://{{url}}/e-sitef/api/v2/payments/"
--header "Content-Type: application/json"
--header "merchant_id: xxxxxxxx"
--header "merchant_key: xxxxxxxxxxx"
--data-binary
{
"merchant_usn":"1709151775",
"order_id":"0001709151774770",
"installments":"1",
"installment_type":"4",
"authorizer_id":"2",
"amount":"100",
"soft_descriptor": "Empresa Aluguel de carros XYZ",
"card":{
"number":"555555555555555",
"expiry_date":"1227",
"security_code":"157",
"cryptogram": "ALRzlt6NKQtPAAZAkOuIAAADFA==",
"wallet_type": "network_token"
}
}
--verbose

Response parameters

ParameterDescriptionFormat
card
parEMVCo introduced PAR (Payment Account Reference) to provide an industry-aligned approach designed to help link all token-based transactions associated with a specific account.< 32
suffixLast four digits of the PAN, returned by Visa and Mastercard in transactions carried out with DPAN (Network Token).= 4

Payment Response:

{
"code": "0",
"message": "OK. Transaction successful.",
"payment": {
"authorizer_code": "000",
"authorizer_message": "TRANSACAO APROVADA",
"status": "CON",
"nit": "1854a5dac2033afc012c4ed807183bf77f6179a75c79ec81c770a0bde8aef583",
"order_id": "0001709151774770",
"customer_receipt": "====CUPOM COMPRADOR====",
"merchant_receipt": "====CUPOM ESTABELECIMENTO====",
"authorizer_id": "2",
"acquirer_id": "229",
"acquirer_name": "Bin (Via Servicos TEF)",
"authorizer_date": "28/02/2024T17:22",
"authorization_number": "226596",
"merchant_usn": "1709151775",
"esitef_usn": "240228062687260",
"sitef_usn": "816339",
"host_usn": "43734572890",
"amount": "100",
"payment_type": "C",
"terminal_id": "ES000001",
"card_par": "hI3C1LmpTY46qNx4YlsyOvbRQBg3o",
"payment_date": "28/02/2024T17:22",
"recurrency_tid": "055950827503911"
},
"card": {
"par": "hI3C1LmpTY46qNx4YlsyOvbRQBg3o",
"suffix": "0042"
}
}

Pre-Authorization Request:

curl
--request POST "https://{{url}}/e-sitef/api/v2/preauthorizations/"
--header "Content-Type: application/json"
--header "merchant_id: xxxxxxxx"
--header "merchant_key: xxxxxxxxxxx"
--data-binary
{
"merchant_usn":"1709151775",
"order_id":"0001709151774770",
"installments":"1",
"installment_type":"4",
"authorizer_id":"2",
"amount":"100",
"soft_descriptor": "Empresa Aluguel de carros XYZ",
"card":{
"number":"555555555555555",
"expiry_date":"1227",
"security_code":"157",
"cryptogram": "ALRzlt6NKQtPAAZAkOuIAAADFA==",
"wallet_type": "network_token"
}
}
--verbose

Pre-Authorization Response:

{
"code": "0",
"message": "OK. Transaction successful.",
"card": {
"par": "A80pcFJxz0FgEK6qDggFpM5KUl2Jf",
"suffix": "0042"
},
"pre_authorization": {
"authorizer_code": "000",
"authorizer_message": "TRANSACAO APROVADA",
"status": "CON",
"nit": "74e3fa7509d683c73240e4868ec7b75b14170547567b809f6f2698f234ab8f4f",
"order_id": "0001709151682784",
"customer_receipt": "====CUPOM COMPRADOR====",
"merchant_receipt": "====CUPOM ESTABELECIMENTO====",
"authorizer_id": "2",
"acquirer_id": "2651",
"acquirer_name": "Bin (Via Servicos TEF)",
"authorizer_date": "28/02/2024T17:21",
"authorization_number": "242440",
"merchant_usn": "1709151683",
"esitef_usn": "240228062687254",
"sitef_usn": "304331",
"host_usn": "43734572891",
"amount": "100",
"payment_type": "C",
"terminal_id": "ES000001",
"card_par": "A80pcFJxz0FgEK6qDggFpM5KUl2Jf",
"recurrency_tid": "969452034274685"
}
}