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:

Parameter	Description	Format	Mandatory
`external_authentication`
`ucaf_sli`	Contains the UCAF (Universal Cardholder Authentication Field), which corresponds to SLI's last digit (Security Level Indicator) from Mastercard Secure Code.	= 1 N	NO
`version`	3DS version (`1` or `2`).	= 1 N	NO
`reference_id`	Directory Server identifier for 3DS 2.0 transactions.	< 36 AN	NO
`tavv`	DSRP-UCAF tokenized transaction cryptogram.	< 40 AN	NO
`cavv`	Cardholder Authentication Verification Value - Codes that refers to card holder authentication result data.	< 40 N	NO

Card-On-File Parameters#

Definitions#

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

`usage`	Definition
`first`	Indicate the first ocurrency
`subsequent`	Indicate subsequent ocorrences of a recurrency
`authorized`	To be used together `reason=card` parameter indicating that the card holder has authorized the card storage

`reason`	Definition
`cardholder`	Subsequent purchases triggered by the cardholder
`unscheduled`	Subsequent purchases without scheduling
`recurring`	Scheduled recurrent purchases
`installment`	Instalment thru recurrency
`card`	To 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)

Sigla	Definition
CIT	is any transaction where the cardholder is actively participating in the transaction, either at a terminal in-store or through a checkout experience online.
MIT	is 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#

`usage`	`reason`	Definition	MIT/CIT?
`authorized`	`card`	Indicates that the cardholder has authorized the storage of the card	CIT
`first`	`unscheduled`	Indicates a single payment	MIT
`first`	`recurring`	Indicates the first the first occurrence of a recurrence	MIT
`subsequent`	`recurring`	Indicates subsequent occurrences of a recurrence	MIT
`subsequent`	`cardholder`	Indicates a payment made by the user with the card already stored	CIT
`subsequent`	`unscheduled`	Indicates a subsequent unscheduled occurrence initiated by the merchant	MIT
`subsequent`	`installment`	Indicates installment by recurrence	MIT

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.

Parameter	Description	Format	Required
`card`
`number`	Token generated by the brand (DPAN)	≤ 19 N	Yes
`cryptogram`	Cryptogram generated by the brand	= 28 A	Yes for network token payments
`wallet_type`	Field that specifies whether the transaction is processed with PAN or DPAN. You must send the value “network_token” for tokenized transactions.	AN	Yes 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

Parameter	Description	Format
`card`
`par`	EMVCo 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
`suffix`	Last 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"
    }
}