The merchant has the possibility to configure the routing of transactions made in Carat Portal, one of these routings is Bradescard.

Supported Carat Portal interfaces#

We will use the following interfaces for integration with Bradescard routing:

  • REST Payment
  • HTML Payment
  • REST Cancellation
  • Cancellation via Merchant's Portal
  • REST Generic operations for Bradescard queries

Bradescard query service#

In the Bradescard queries, it is possible to make the statement summary query and to make the balance query of a specific card.

Call details#

The Bradescard query service is provided by the generic operation interface (Learn more). The Bradescard query operation is mandatory the authenticity token for each query performed, so it is necessary to obtain the token (Learn more) and then perform the generic operation call (Learn more).

The Bradescard query is identified with operation code 172 (use this value in the operation field in the request).

Parameters of Bradescard queries#

Below are the parameters that are used by the request for Bradescard query operation.

dateFiscal date.NNo
timeFiscal hour.NNo
subfunctionQuery transaction subfunction. The following queries are planned:
01 - Balance query
02 - Statement Summary query
2 NNo
card_entry_modeEntry mode. The possible values for this field are:
1 – Magnetic card
2 – Card number entered
1 NYes
card_numberThis field must be filled with the card number.NConditional
Yes, if card_entry_mode_type is equal to "2"
track1This field must be filled with the track 1 of the card.< 99 ANConditional
Yes, if card_entry_mode_type is equal to "1"
track2This field must be filled with the track 2 of the card.< 99 NConditional
Yes, if card_entry_mode_type is equal to "1"
card_expiry_dateCard expiration date.4 N (MMYY)Conditional
Yes, if card_entry_mode_type is equal to "2"
card_security_codeSecurity code.< 10 NConditional
Yes, if requested in the card query (Learn more).
card_issue_dateCard issue date.6 N (MMYYYY)Conditional
Yes, if requested in the card query (Learn more).

Response parameters#

If successful, the HTTP response code will be 200. Any other code must be interpreted as an error. In the table below is the description of the response parameters of the Bradescard query service:

response_codeCarat Portal response code.
response_messageReply message from Carat Portal.
authorizer_response_codeAuthorizer response code.
authorizer_response_messageAuthorizer reply message.
parameters.acquirer_idAcquirer id in SiTef.
parameters.host_usnHost USN.
parameters.sitef_usnSiTef USN.
parameters.institution_response_codeAuthorizer/acquirer response code.
parameters.institution_nameInstitution Name.
parameters.authorization_numberAuthorization number.
parameters.affiliation_codeMerchant affiliation code in authorizer/acquirer.
parameters.confirmation_dataConfirmation data.
parameters.customer_receiptCustomer's receipt.
parameters.merchant_receiptMerchant's receipt.
parameters.sale_response_dataSale response data.

Response codes

See reference on API codes - response codes

Additional parameters#

The fields below must be inserted inside the additional_data structure of transaction creation call. (Learn more)

additional_dataElement for sending additional data.
skip_cycles_daysIndicates the payment postponement in days for credit purchases in installments.< 2 NNO
skip_cycles_periodsIndicates the payment postponement in periods or cycles for credit purchases in installments.< 2 NNO
free_installments_indicatorIndicates the existence of free installment.
1-Indicates true
0 or not informed-indicates false
card_holder_biometric_authenticationInformation regarding biometric authentication.< 6 ANNO

Parameters details#

skip_cycles_daysNumber of days in 99 format. Example: 30
Absence indicates non-use of this functionality.
skip_cycles_periodsNumber of periods or cycles in 99 format. Example 01
Absence indicates non-use of this functionality.
free_installments_indicator0-Indicates without free installment.
1-Indicates with free installment.
   Absence is assumed with the value 0
card_holder_biometric_authenticationX;Y where
   X - Authentication type code, with values:
      1-Customer since MM/YY (Y Format is YYMM)
      2-Biometrics (without sending values in Y)
      3-Account stored (without sending values in Y)
   Y-Information regarding the type of authentication of the cardholder.



Below is a example of the transaction creation service call using the cURL tool.


To use this example, don't forget to define the variable {{url}} with the value

--request POST ""
--header "Content-Type: application/json"
--header "merchant_id: xxxxxxxx"
--header “merchant_key: xxxxxxxxxxx”
"additional_data": {
"skip_cycles_days": "45",
"free_installments_indicator": "1"


"code": "0",
"message": "OK. Transaction successful.",
"payment": {
"status": "NOV",
"nit": "1234567890abcdefghijklmnopqrstuvwxyz1234567890abcdefghijklmnopqr",
"order_id": "12042142155",
"merchant_usn": "12042142155",
"amount": "1000"

Bradescard Voucher#

Bradescard Voucher allows a customer who does not yet have a Bradescard's card to make a purchase with this card in a Bradescard's partner store. This case is exclusive for Bradescard route.

In this case, there are two scenarios:

  • The store do have a Bradescard card printer, so it prints the card on the fly;
  • The store does not have a Bradescard Card Printer, so it generates a request and receive a PDF containing all necessary information to carry out the transaction.

Supported Carat Portal Interfaces#

We will use the following interfaces for integration with Bradescard Voucher routing:

  • REST Payment
  • REST Cancellation
  • Cancellation via Merchant's Portal

REST Payment#

Payment using Bradescard Voucher follows REST Payments default transactional flow, being differentiated by sending the following mandatory fields during the payment step:

  • card.number - fictional card number;
  • acquirer.authorization_number - voucher authorization code.

Other fields related to card date are not used.


The cancellation of transactions via Bradescard Voucher follows the existing flow, without the need of sending extra fields new.

For cancellation via Merchant's Portal, it is necessary to fill the card number used in the transaction.

For more details, refer to the following documentation:

Balance and Statement Inquiries#

The Bradescard Voucher does not allow balance and statement inquiries.