Transactions API - Clara API

In version 3 of the Transactions API, Clara offers real-time access to card transactions through a paginated RESTful service.

When does a Transactions Appear?

Most transactions appear in the API almost instantly. However, some are delayed until Mastercard confirms them through the reconciliation process. This can take up to 2 business days. Initially, you’ll see a pre-authorization, which becomes authorized after confirmation.

Transaction Types

PURCHASE: A cardholder buys a product/service.
REFUND: A merchant reimburses the cardholder usually due to a product return or an error in processing the purchase.
FEE: Additional charges from services or admin costs.
CREDIT: Clara adds balance to the account (e.g., refund, adjustments, rewards).
PAYMENT: Outgoing payment, like a credit card bill, a debt, or any other financial obligation

Transaction Lifecycle

Transactions can have different statuses, which may change throughout the transaction cycle.

NOTIFICATION (ON): Initial transaction record.
PRE_AUTHORIZED (AU): Issuer confirms funds and card validity.
AUTHORIZED (OP): Reconciled and finalized.
REJECTED (RJ): Failed or canceled transaction.
SYSTEM_TRANSACTION (EC): Special status for FEE, PAYMENT, or CREDIT.

Pagination Details

Each page shows up to 100 transactions, with support for filters and sorting to tailor responses.

cURL

curl -X GET
"https://public-api.mx.clara.com/api/v3/transaction?size=1" \ 
-H "Authorization: Bearer YOUR_ACCESS_TOKEN"

JSON

{
  "transactionUuid": "47f8ed9e-4d7b-450b-ad6a-f1d83e3ce4e1",
  "invoices": [
    {
      "invoiceId": "54cd6b23-5146-437f-b133-879c432e6776",
      "invoiceNumber": null,
      "taxRegime": "621",
      "issuer": {
        "rfc": "CLARA123XML",
        "businessName": "CLARA"
      },
      "taxReceipts": {
        "cfdi": "G03",
        "paymentMethod": "Q4"
      },
      "tax": {
        "retained": {
          "isr": 0.75,
          "iva": null,
          "ieps": null
        },
        "transferred": {
          "iva": 0.0,
          "ieps": 0.0
        }
      },
      "amount": {
        "total": 400.00,
        "subTotal": 300.00,
        "currency": "MXN"
      },
      "documentDate": "2024-10-01",
      "xmlStatus": "Vigente",
      "xmlCode": "S – Comprobante obtenido satisfactoriamente."
    }
  ]
}

How to Retrieve Attachments

As a platform, Clara provides its clients with the ability to attach files to transactions, such as receipts, invoices, or other relevant information that can assist in their reconciliation process. To facilitate this, we provide download links for these attachments. If a transaction has attachments:

The hasAttachments field is set to true
You’ll receive a** link to download them**
URLs are valid for 12 hours

Format: .../v3/transactions/{uuid}/documents In the following example, we will get the URLs for the transaction with the UUID “47f8ed9e-4d7b-450b-ad6a-f1d83e3ce4e1” in Mexico.

cURL

curl -X GET
"https://public-api.mx.clara.com/api/v3/transactions/47f8ed9e-4d7b-450b-ad6a-f1d83e3ce4e1/documents" \ 
-H "Authorization: Bearer YOUR_ACCESS_TOKEN"

JSON

{
  "transactionUuid": "47f8ed9e-4d7b-450b-ad6a-f1d83e3ce4e1",
  "attachments": [
    {
      "uuid": "18589896-d30e-4cca-a4e6-716ba323b937",
      "fileName": "receipt.jpg",
      "updateAt": "2024-12-09T01:35:26.426484Z",
      "format": "jpeg",
      "download": {
        "urlExpiration": "2024-12-14T07:40:15.144358891Z",
        "url": "https://company-9fefb4f5-491d-4028-8c4d-f7b20ff98e29.s3.amazonaws.com/user_docs/1dbf684e-4cdd-467d-b240-3e8e45d63887/51/5465258?response-content-disposition=attachment%3B%20filename%3D%22oneOoneHuixquilucan_241208193512.jpg%22&response-content-type=jpeg&X-Amz-Security-Token=FwoGZXIvYXdzEDUaDJAr429nJB6KRbni%2FiKwAbLEsGgPIsSE8kV0DdR905%2FXd4wYq9zQ2P99MHz06fykkTuaylb7xbpkANXyqQpTJw2M23Q%2FabFuakuazkVDPCQ%2BHwDM3LmJ%2BqWhng87m1q6p6JlacCyMqlQbVtpwYFcts1hMjSXASha79Cs%2FLm9onR2txbq6rTn5%2BW0vtKFk%2FyD7x%2FhGhfmMuZyUgD37dp7FSzUo0Z4ZjLhHjrc6tt%2F2f2C15sN1ps9tCtoyyCiKJ2b8roGMi0W6DxWRVjX7xCGyIT07lfVCMnw9v1MsbpscZ5%2BORVmaTq9CfU3kezypy%2B0M%3D&X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Date=20241213T194014Z&X-Amz-SignedHeaders=host&X-Amz-Expires=43199&X-Amz-Credential=ASIASUFA8KD3C1GJLWK%2F20241213%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Signature=3038ebf880b3cd0a0e8b24a0440f047e52ec1f4c1b88f210c637928747a688cc"
      }
    }
  ]
}

Invoice Info (Mexico Only)

Clara also provides a space to upload invoice XML files, available only in Mexico. If a transaction has invoice:

The hasInvoice field is set to true
You’ll receive a link to download them
URLs are valid for 12 hours

Format: .../v3/transactions/{uuid}/invoices In the following example, we will get the invoice information for the transaction with the UUID “47f8ed9e-4d7b-450b-ad6a-f1d83e3ce4e1” in Mexico.

cURL

curl -X GET
"https://public-api.mx.clara.com/api/v3/transactions/47f8ed9e-4d7b-450b-ad6a-f1d83e3ce4e1/invoices" \ 
-H "Authorization: Bearer YOUR_ACCESS_TOKEN"

JSON

{
  "transactionUuid": "47f8ed9e-4d7b-450b-ad6a-f1d83e3ce4e1",
  "invoices": [
    {
      "invoiceId": "54cd6b23-5146-437f-b133-879c432e6776",
      "invoiceNumber": null,
      "taxRegime": "621",
      "issuer": {
        "rfc": "CLARA123XML",
        "businessName": "CLARA"
      },
      "taxReceipts": {
        "cfdi": "G03",
        "paymentMethod": "Q4"
      },
      "tax": {
        "retained": {
          "isr": 0.75,
          "iva": null,
          "ieps": null
        },
        "transferred": {
          "iva": 0.0,
          "ieps": 0.0
        }
      },
      "amount": {
        "total": 400.00,
        "subTotal": 300.00,
        "currency": "MXN"
      },
      "documentDate": "2024-10-01",
      "xmlStatus": "Vigente",
      "xmlCode": "S – Comprobante obtenido satisfactoriamente."
    }
  ]
}

Note: The examples provided do not contain real data, and they do not reflect actual calculations for fees, taxes, or any other financial details.

How to Retrieve Extracted Documents

Use GET /api/v3/transactions/{uuid}/extracted-documents to get structured, validated documents like XML invoices or receipts.

Authentication:

Use MTLS for secure two-way certificate validation.
Include a valid OAuth2 token, via the /oauth/token endpoint.
Include the Bearer token in the Authorization header of your request.

Endpoint:

Text

GET
"/api/v3/transactions/{uuid}/extracted-documents"

Base URL examples:

https://public-api.mx.clara.com
https://public-api.br.clara.com
https://public-api.co.clara.com

Path Parameter:

Name		Type	Required	Description
uuid		string	✅ Yes	UUID of the transaction

Query Parameters:

Name	Type	Description
page	integer	Page index, zero-based. Default: 0
size	integer	Items per page. Default: 20
uuid	uuid	Filter by extracted document UUID
type	enum	Filter by document type: `MEXICAN_FISCAL_INVOICE`, `INVOICE`, `RECEIPT`, `OTHER`
validationStatus	enum	Filter by validation status: `VALIDATED_BY_CLARA`, `VALIDATED_BY_USER`, `NOT_VERIFIED`

Response:

Returns a paginated list of extracted documents associated with the transaction. Each document includes metadata and content such as:

JSON

{
  "uuid": "123e4567-e89b-12d3-a456-426614174000",
  "type": "INVOICE",
  "userUuid": "cd22be0b-c074-41d3-8645-77e1507c8562",
  "data": {
    "folioFiscalUuid": "123e4567-e89b-12d3-a456-426614174000",
    "invoiceId": "INV-2023-001",
    "receiptDate": "2023-10-15",
    "issueDate": "2023-10-15",
    "billingDate": "2023-10-31",
    "country": "MX",
    "issuer": {
      "legalName": "ACME Corporation",
      "taxIdentifier": "ABC123456XYZ"
    },
    "items": [
      {
        "name": "Office Chair",
        "unitPrice": 149.99,
        "quantity": 2,
        "total": 299.98
      }
    ],
    "itemsDescription": "Office supplies",
    "amount": {
      "currency": "USD",
      "subTotal": 100.0,
      "taxesAmount": 16.0,
      "tipAmount": 10.0,
      "total": 126.0,
      "taxPercentage": 16.0,
      "tipPercentage": 10.0
    }
  },
  "fileValidation": {
    "status": "VALIDATED_BY_CLARA",
    "date": "2023-10-15T14:30:00",
    "user": "John Doe",
    "userUuid": "123e4567-e89b-12d3-a456-426614174000"
  }
}

Validation Status Details

Status	Description
VALIDATED_BY_CLARA	Automatically validated successfully
VALIDATED_BY_USER	Validated manually by a user
NOT_VERIFIED	Document could not be validated

Successful Response

Status	Meaning
200	OK - List of extracted documents returned

Error Responses

Status	Meaning
400	Bad Request
401	Unauthorized
403	Forbidden

Example cURL Request

curl --location --request GET 'https://public-api.mx.clara.com/api/v3/transactions/{uuid}/extracted-documents' \
--header 'Authorization: Bearer {your_access_token}' \
--cert {client_cert_path} \
--key {client_key_path}

Replace {uuid}, {your_access_token}, {client_cert_path}, and {client_key_path} with actual values.

Summary

This endpoint enables retrieval of structured, validated financial documents (invoices, receipts, etc.) tied to a transaction. It supports robust filtering and pagination, and enforces secure access through MTLS and OAuth2.

Endpoint Reference

`GET /api/v3/transactions`

List all transactions (v3) Parameters:

Parameter	In	Type	Description
`page`	query	integer	Page index, zero-based. Default: `0`
`size`	query	integer	Items per page. Default: `20`, max: `100`
`lastUpdateDateRangeStart`	query	string (date)	Filter by last update date start
`lastUpdateDateRangeEnd`	query	string (date)	Filter by last update date end
`operationDateRangeStart`	query	string (date)	Filter by operation date start
`operationDateRangeEnd`	query	string (date)	Filter by operation date end
`accountingDateRangeStart`	query	string (date)	Filter by accounting date start
`accountingDateRangeEnd`	query	string (date)	Filter by accounting date end
`userUuid`	query	string (uuid)	Filter by user UUID
`cardUuid`	query	string (uuid)	Filter by card UUID
`cardLastDigits`	query	string	Filter by last 4 digits of card
`userErpId`	query	string	Filter by user ERP ID
`status`	query	string	Filter by transaction status
`operationTypeCode`	query	string	Filter by operation type code

Response Schema (TransactionPageV3):

Field	Type	Example
`content`	array of TransactionResponseV3
`totalElements`	integer	`150`
`totalPages`	integer	`8`
`size`	integer	`20`
`number`	integer	`0`

`GET /api/v3/transactions/{uuid}`

Get transaction by UUID (v3) Parameters:

Parameter	In	Type	Required	Description
`uuid`	path	string (uuid)	✅

Response Schema (TransactionResponseV3):

Field	Type	Example
`uuid`	string (uuid)	`4ea5a94a-2c3c-4601-b623-c30260c21dbc`
`type`	string	`PURCHASE`
`transactionLabel`	string	`OPENAI SUBSCR`
`labels`	array of TransactionLabel
`status`	string	`AUTHORIZED`
`comment`	string	`Tool to improve`
`billingStatement`	object (BillingStatementTransactionRef)
`accountingFields`	array of AccountingFields
`audit`	object (Audit)
`merchant`	object (Merchant)
`card`	object (TransactionCard)
`user`	object (TransactionUser)
`authorizationNumber`	string	`001921`
`originalAmount`	object (CurrencyAmount)
`amountValue`	object (CurrencyAmount)
`validationStatus`	object (ValidationStatus)
`hasInvoice`	object (Has)
`hasAttachments`	object (Has)
`hasExtractedDocuments`	object (Has)
`installment`	string	`None`
`installmentNumber`	string	`None`
`bankConcept`	object (BankConcept)
`links`	array of Link

`POST /api/v3/transactions/{uuid}/comment`

Add a comment to a transaction. Parameters:

Parameter	In	Type	Required	Description
`uuid`	path	string (uuid)	✅

Request Body:

Field	Type	Required	Description
`comment`	string	✅	Comment text

Response (201):

{
  "comment": "Expense approved by finance",
  "transactionsUuids": ["8108ed5a-3de7-479e-8431-b5824db5044d"]
}

`DELETE /api/v3/transactions/{uuid}/comment`

Remove the comment from a transaction. Returns 204 No Content. Parameters:

Parameter	In	Type	Required	Description
`uuid`	path	string (uuid)	✅

`GET /api/v3/transactions/{uuid}/invoices`

Get transaction invoices (Mexico fiscal) Parameters:

Parameter	In	Type	Required	Description
`uuid`	path	string (uuid)	✅

Response Schema (TransactionInvoiceResponse):

Field	Type	Example
`content`	array of InvoiceV3
`totalElements`	integer
`totalPages`	integer
`size`	integer
`number`	integer

`POST /api/v3/transactions/comments/bulk`

Bulk add comments to multiple transactions in a single request. Request Body:

Field	Type	Description
`transactions`	array	Each item must include `uuid` (transaction UUID) and `comment` (string)

Example:

{
  "transactions": [
    { "uuid": "4ea5a94a-2c3c-4601-b623-c30260c21dbc", "comment": "Approved" },
    { "uuid": "8108ed5a-3de7-479e-8431-b5824db5044d", "comment": "Pending review" }
  ]
}

`POST /api/v3/transactions/labels/bulk`

Bulk bind labels to multiple transactions in a single request. Request Body:

Field	Type	Description
`transactions`	array	Each item must include `uuid` (transaction UUID) and `labelsUuid` (array of label UUIDs)

Example:

{
  "transactions": [
    {
      "uuid": "4ea5a94a-2c3c-4601-b623-c30260c21dbc",
      "labelsUuid": ["0169fe8b-b5e1-46f0-895d-a79d2753fee1"]
    }
  ]
}

`GET /api/v3/transactions/{uuid}/documents`

Get transaction documents (v3) Parameters:

Parameter	In	Type	Required	Description
`uuid`	path	string (uuid)	✅

Response Schema (AttachmentDocuments):

Field	Type	Example
`uuid`	string (uuid)
`attachments`	array of AttachmentItem

`GET /api/v3/transactions/{uuid}/extracted-documents`

Get extracted documents for transaction (v3) Parameters:

Parameter	In	Type	Required	Description
`uuid`	path	string (uuid)	✅
`documentUuid`	query	string (uuid)		Filter by document UUID
`type`	query	string		Filter by document type
`validationStatus`	query	enum: `VALIDATED_BY_CLARA`/`VALIDATED_BY_USER`/`NOT_VERIFIED`		Filter by validation status

Response Schema (ExtractedDocumentPage):

Field	Type	Example
`content`	array of ExtractedDocument
`totalElements`	integer
`totalPages`	integer
`size`	integer
`number`	integer

​When does a Transactions Appear?

​Transaction Types

​Transaction Lifecycle

​Pagination Details

​How to Retrieve Attachments

​Invoice Info (Mexico Only)

​How to Retrieve Extracted Documents

​Authentication:

​Endpoint:

​Path Parameter:

​Query Parameters:

​Response:

​Validation Status Details

​Successful Response

​Error Responses

​Example cURL Request

​Summary

​Endpoint Reference

​GET /api/v3/transactions

​GET /api/v3/transactions/{uuid}

​POST /api/v3/transactions/{uuid}/comment

​DELETE /api/v3/transactions/{uuid}/comment

​GET /api/v3/transactions/{uuid}/invoices

​POST /api/v3/transactions/comments/bulk

​POST /api/v3/transactions/labels/bulk

​GET /api/v3/transactions/{uuid}/documents

​GET /api/v3/transactions/{uuid}/extracted-documents

When does a Transactions Appear?

Transaction Types

Transaction Lifecycle

Pagination Details

How to Retrieve Attachments

Invoice Info (Mexico Only)

How to Retrieve Extracted Documents

Authentication:

Endpoint:

Path Parameter:

Query Parameters:

Response:

Validation Status Details

Successful Response

Error Responses

Example cURL Request

Summary

Endpoint Reference

`GET /api/v3/transactions`

`GET /api/v3/transactions/{uuid}`

`POST /api/v3/transactions/{uuid}/comment`

`DELETE /api/v3/transactions/{uuid}/comment`

`GET /api/v3/transactions/{uuid}/invoices`

`POST /api/v3/transactions/comments/bulk`

`POST /api/v3/transactions/labels/bulk`

`GET /api/v3/transactions/{uuid}/documents`

`GET /api/v3/transactions/{uuid}/extracted-documents`