Docs
DocsAPI RestRecipesTutorialsHelp

Queries

Suggest Edits

Queries

Brazil

Queries - V1 Unified

1. Unified Transaction Query

Provides a main endpoint for transaction lookup with support for filters via headers and query params, plus pagination. Delivers a unified transaction/payment-link query across the Carat ecosystem, enabling the Fiserv Acquiring portal to query all transactions for a store regardless of the transaction origin channel.

Call details

  • Resource: /v1/transactions
  • HTTP Method: GET
  • Request format: query string
  • Response format: JSON
  • Headers: merchant_id, merchant_key, group_id
  • Query params:
    • merchant_id_query — target merchant id for the query (e.g. LOJAMTRG2)
    • start_date — start date in dd/MM/yyyy format (e.g. 01/06/2026)
    • end_date — end date in dd/MM/yyyy format (e.g. 30/06/2026)
    • status — transaction status (e.g. AUTORIZADA)
    • payment_link — filters payment link transactions (e.g. true)
    • page — page number, starting at 0 (e.g. 0)
    • limit — number of records per page (e.g. 20)
    • size — limit alias for backward compatibility (e.g. 20)

Example

Request:

curl -X GET "https://{{url}}/v1/transactions?merchant_id_query=LOJAMTRG2&start_date=01/06/2026&end_date=30/06/2026&status=AUTORIZADA&page=0&limit=20" \
--header "merchant_id: LOJAMTRG1" \
--header "merchant_key: F19DE00177C301DF24A865F11AA9B256" \
--header "group_id: 123"

Response:

{
  "code": "200",
  "message": "Query executed successfully",
  "transactions": [
    {
      "status": "AUTORIZADA",
      "merchant_id": "LOJAMTRG1",
      "order_id": "123456",
      "amount": "100.00"
    }
  ],
  "current_page": "0",
  "total_pages": "1",
  "count": "1"
}

Queries - V1 Double Request

1. Transaction Status Query

These services can be called to obtain data from payment, cancel, or schedule transactions. They are essential for communication-failure handling and for checking the current transaction state on Carat.

Call details

  • Query by NIT
    • Resource: /v1/transactions/{nit}
    • HTTP Method: GET
    • Response format: JSON
  • Query by SID
    • Resource: /v1/schedules/{sid}
    • HTTP Method: GET
    • Response format: JSON
  • Headers: merchant_id, merchant_key

Examples

Request (payment query):

curl 
--request GET "https://{{url}}/e-sitef/api/v1/transactions/1234567890abcdefghijklmnopqrstuvwxyz1234567890abcdefghijklmnopqr"
--header "merchant_id: xxxxxxxxxxxxxxx"
--header "merchant_key: xxxxxxxxxxx"
--verbose

Response (payment):

{
   "code":"0",
   "message":"OK. Transaction successful.",
   "payment":{
      "authorizer_code":"000",
      "authorizer_message":"Transacao OK",
      "status":"CON",
      "nit":"1234567890abcdefghijklmnopqrstuvwxyz1234567890abcdefghijklmnopqr",
      "order_id":"13064421440",
      "customer_receipt":"==== CUPOM COMPRADOR ====",
      "merchant_receipt":"==== CUPOM ESTABELECIMENTO ====",
      "authorizer_id":"2",
      "acquirer_id":"229",
      "acquirer_name":"Bin",
      "authorizer_date":"13/07/2017T18:44",
      "authorization_number":"132048",
      "merchant_usn":"13064421441",
      "esitef_usn":"170713097341620",
      "sitef_usn":"132048",
      "host_usn":"999132048   ",
      "payment_date":"13/07/2017T18:44",
      "amount":"1000",
      "payment_type":"C",
      "issuer":"2",
      "authorizer_merchant_id":"000000000000005"
   }
}

2. Card Query

Source: https://docs.apis-fiserv.com/latam/docs/pagamento-rest-cardquery

Allows BIN/card capability query in payment context, usually from a payment transaction with status NOV.

Call details

  • Resource: /v1/payments/{nit}/cards
  • HTTP Method: POST
  • Request format: JSON
  • Response format: JSON
  • Headers: Content-Type, merchant_id, merchant_key

Examples

Request:

curl 
--request POST "https://{{url}}/e-sitef/api/v1/payments/1234567890abcdefghijklmnopqrstuvwxyz1234567890abcdefghijklmnopqr/cards"
--header "Content-Type: application/json"
--header "merchant_id: xxxxxxxxxxx"
--header "merchant_key: xxxxxxxxxxx"
--data-binary
{
   "card":{
      "number":"5555555555555555"
   },
   "authorizer_id":"1"
}
--verbose

Response:

{
  "code": "0",
  "message": "OK. Transaction successful.",
  "payment": {
    "status": "NOV"
  },
  "card": {
    "acquirer_name": "Bin",
    "authorizer_id": "1",
    "authorizer_response_code": "000",
    "is_customer_id_required": "false",
    "is_expiry_date_required": "true",
    "is_installment_funding_enabled": "true",
    "is_security_code_required": "true",
    "is_spot_sale_enabled": "true",
    "is_with_interest_sale_enabled": "true",
    "is_without_interest_sale_enabled": "true",
    "max_installments_with_interest": "12",
    "min_installments_with_interest": "01",
    "prefixes": {
      "TRAT": "2",
      "PERIFERICO": "1",
      "CSEG": "2"
    }
  }
}

3. Pre-Authorization Status Query

Source: https://docs.apis-fiserv.com/latam/docs/pre-autorizacao-rest-getstatus

Used after communication failure/timeout to check status of pre-authorization flow transactions (within retention window), using nit.

Call details

  • Resource: /v1/transactions/{nit}
  • HTTP Method: GET
  • Request format: JSON
  • Response format: JSON
  • Headers: Content-Type, merchant_id, merchant_key

Example

Request:

curl
--request GET "https://{{url}}/e-sitef/api/v1/transactions/1234567890abcdefghijklmnopqrstuvwxyz1234567890abcdefghijklmnopqr"
--header "Content-Type: application/json"
--header "merchant_id: xxxxxxxx"
--header "merchant_key: xxxxxxxxxxx"
--verbose

Response (excerpt):

{
  "code": "0",
  "message": "OK. Transaction successful.",
  "pre_authorization": {
    "status": "CON",
    "nit": "1234567890abcdefghijklmnopqrstuvwxyz1234567890abcdefghijklmnopqr",
    "order_id": "oioi",
    "merchant_usn": "20180809",
    "amount": "1470"
  },
  "capture": {
    "status": "CON",
    "nit": "abcdefghijklmnopqrstuvwxyz1234567890abcdefghijklmnopqr1234567890",
    "order_id": "201808020001",
    "merchant_usn": "20180809",
    "amount": "1380"
  }
}

4. Card Query (Pre-Authorization)

Source: https://docs.apis-fiserv.com/latam/docs/pre-autorizacao-rest-docardquery

BIN/card capability query in pre-authorization context, from pre-authorization transaction nit in status NOV.

Call details

  • Resource: /v1/preauthorizations/{nit}/cards
  • HTTP Method: POST
  • Request format: JSON
  • Response format: JSON
  • Headers: Content-Type, merchant_id, merchant_key

Example

Request:

curl
--request POST "https://{{url}}/e-sitef/api/v1/preauthorizations/1234567890abcdefghijklmnopqrstuvwxyz1234567890abcdefghijklmnopqr/cards"
--header "Content-Type: application/json"
--header "merchant_id: xxxxxxxxxxx"
--header "merchant_key: xxxxxxxxxxx"
--data-binary
{
    "card":{
        "number":"5555555555555555"
    },
    "authorizer_id":"1"
}
--verbose

Response:

{
  "code": "0",
  "message": "OK. Transaction successful.",
  "preauthorization": {
    "status": "NOV"
  },
  "card": {
    "acquirer_name": "Bin",
    "authorizer_id": "1",
    "authorizer_response_code": "000",
    "is_installment_funding_enabled": "true",
    "is_security_code_required": "true",
    "max_installments_with_interest": "12",
    "min_installments_with_interest": "01"
  }
}

5. Recharge Query

Source: https://docs.apis-fiserv.com/latam/docs/recarga-rest-getstatus

Allows store-side status query of recharge transactions and related payment data after recharge creation.

Call details

  • Resource: /v3/recharge/{nit}
  • HTTP Method: GET
  • Request format: query string
  • Response format: JSON
  • Authentication: Authorization: Bearer {signature}

Example

Request:

curl 
--request GET "https://{{url}}/e-sitef/v3/recharge/asdfghjk12345678asdfghjk12345678asdfghjk12345678asdfghjk12345678/?merchantkey=ASDFGHJK12345678ASDFGHJK12345678"
--verbose

Response (excerpt):

{
   "get_status_recharge_response":{
      "status":"CON",
      "esitef":{
         "message":"OK",
         "code":"0"
      },
      "payment":{
         "status":"PPC",
         "amount":"12",
         "type":"C",
         "authorizer_id":"1",
         "acquirer":"CIELO"
      }
   }
}

Queries - V2 Single Request

6. Query by order_id

Source: https://docs.apis-fiserv.com/latam/docs/consulta-orderid

Queries payment/cancel transactions by order_id, useful for reconciliation and communication-failure handling.

Call details

  • Resource: /v2/transactions?order_id={order_id}
  • HTTP Method: GET
  • Request format: query string
  • Response format: JSON
  • Headers: Content-Type, merchant_id, merchant_key

Example

Request:

curl  --location --request GET 'https://{{url}}/e-sitef/api/v2/transactions?order_id=123456' \
--header 'Content-Type: application/json' \
--header 'merchant_id: *********' \
--header 'merchant_key: *********'

Response (excerpt):

{
  "code": "0",
  "message": "OK",
  "transactions": [
    {
      "code": "0",
      "message": "OK. Transaction successful.",
      "payment": {
        "status": "CON",
        "order_id": "1659445331723",
        "nit": "8bea6787a4121c65dc84a6ae02330a790c7c1a2730d76fe98b81bca1a2639adc",
        "amount": "3300"
      }
    }
  ],
  "current_page": "0",
  "total_pages": "1",
  "count": "1"
}

7. Query

Source: https://docs.apis-fiserv.com/latam/docs/consulta

Query service by nit to return payment/refund data. For payment with schedule, response includes both transaction contexts.

Call details

  • Query by NIT
    • Resource: /v2/transactions/{nit}
    • HTTP Method: GET
    • Response format: JSON
  • Query by order_id
    • Resource: /v2/transactions?order_id={order_id}
    • HTTP Method: GET
    • Response format: JSON
  • Headers: Content-Type, merchant_id, merchant_key

Example

Request (query by NIT):

curl  --location --request GET 'https://{{url}}/e-sitef/api/v2/transactions/1234567890abcdefghijklmnopqrstuvwxyz1234567890abcdefghijklmnopqr' \
--header 'Content-Type: application/json' \
--header 'merchant_id: **********' \
--header 'merchant_key: **********'

Response (payment excerpt):

{
  "code": "0",
  "message": "OK. Transaction successful.",
  "payment": {
    "status": "CON",
    "nit": "1234567890abcdefghijklmnopqrstuvwxyz1234567890abcdefghijklmnopqr",
    "order_id": "1660141068187",
    "amount": "10000",
    "authorizer_id": "2",
    "acquirer_name": "Bin"
  }
}

Updated 4 days ago

Did this page help you?