API Reference

💳 Transactions API: How to Use It

Understand transaction flow, data structure, and integration tips

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


⏱ When Does a Transaction 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 -X GET "https://public-api.mx.clara.com/api/v3/transactions?size=1" \
     -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

{
    "content": [
        {
            "uuid": "47f8ed9e-4d7b-450b-ad6a-f1d83e3ce4e1",
            "type": "PURCHASE",
            "transactionLabel": "PURCHASE AT CLARA",
            "labels": [
                {
                    "uuid": "110299ee-31b9-40ab-8961-bdcc6c4124cd",
                    "links": [
                        {
                            "rel": "self",
                            "href": "https://public-api.mx.clara.com/api/v2/labels/110299ee-31b9-40ab-8961-bdcc6c4124cd"
                        }
                    ]
                },
                {
                    "uuid": "c09d7fd2-865a-4228-819f-1e7a6cf09dd0",
                    "links": [
                        {
                            "rel": "self",
                            "href": "https://public-api.mx.clara.com/api/v2/labels/c09d7fd2-865a-4228-819f-1e7a6cf09dd0"
                        }
                    ]
                }
            ],
            "status": "AUTHORIZED",
            "billingStatement": {
                "links": [
                    {
                        "rel": "self",
                        "href": "https://public-api.mx.clara.com/api/v3/billing-statements/04ef1bae-bbd3-4b56-9d8d-94f7645ec302"
                    }
                ]
            },
            "audit": {
                "accountingDate": "2024-11-27",
                "operationDate": "2024-11-27",
                "lastUpdateDate": "2024-12-03"
            },
            "card": {
                "uuid": "ca6f5ce4-ff2d-4391-82c1-d713d672b3ae",
                "maskedPan": "514509******1234",
                "links": [
                    {
                        "rel": "self",
                        "href": "https://public-api.mx.clara.com/api/v2/cards/ca6f5ce4-ff2d-4391-82c1-d713d672b3ae"
                    }
                ]
            },
            "user": {
                "uuid": "d253a344-13d5-4c5d-b397-f6973611082d",
                "holderName": "Gerry Garcia",
                "links": [
                    {
                        "rel": "self",
                        "href": "https://public-api.mx.clara.com/api/v2/users/d253a344-13d5-4c5d-b397-f6973611082d"
                    }
                ]
            },
            "authorizationNumber": "012345",
            "originalAmount": {
                "currency": "USD",
                "amount": 100.00
            },
            "amountValue": {
                "currency": "MXN",
                "amount": 400.00
            },
            "validationStatus": {},
            "hasInvoice": {
                "value": false,
                "links": []
            },
            "hasAttachments": {
                "value": true,
                "links": [
                    {
                        "rel": "self",
                        "href": "https://public-api.mx.clara.com/api/v3/transactions/47f8ed9e-4d7b-450b-ad6a-f1d83e3ce4e1/documents"
                    }
                ]
            },
            "bankConcept": {
                "number": "0005",
                "description": "CONSUMO NACIONAL"
            },
            "links": [
                {
                    "rel": "self",
                    "href": "https://public-api.mx.clara.com/api/v3/transactions/47f8ed9e-4d7b-450b-ad6a-f1d83e3ce4e1"
                }
            ]
        }
    ],
    "pageable": {
        "pageNumber": 0,
        "pageSize": 1,
        "sort": {
            "empty": false,
            "unsorted": false,
            "sorted": true
        },
        "offset": 0,
        "unpaged": false,
        "paged": true
    },
    "totalElements": 212,
    "totalPages": 212,
    "last": false,
    "size": 1,
    "number": 0,
    "sort": {
        "empty": false,
        "unsorted": false,
        "sorted": true
    },
    "numberOfElements": 1,
    "first": true,
    "empty": false
}

📎 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 -X GET "https://public-api.mx.clara.com/api/v3/transactions/47f8ed9e-4d7b-450b-ad6a-f1d83e3ce4e1/documents" \
     -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

{
    "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%2FiKwAblEsGgPIsSE8kVODdR9O5%2FXd4wYq9zQ2P99HMzO6fykkTuaylb7xbpK4NXyqQpTJw2M23QP%2FabFuakuazkVDPCQ%2BHWvDM3LmJ%2BqWbng87m1q6p6JlacCyMQlbVtpwYFcts1hMjSXAsHa79cS%2FLm9onR2txbq0rTn5%2BWOvtXFkK%2FyDXv7Q%2FhGhfMzU2yUgD37dp7FSzU0oZ4ZjlHHjrc6tt2%2Ff2C15sN1ps9tcDtoyCiKJ2b8roGMi0WD6WXRVjX7xCGyITO7lfVCmNwx9w1MsbpscZ5%2BORVmaTq9CfU3kezpyp2%2B0M%3D&X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Date=20241213T194014Z&X-Amz-SignedHeaders=host&X-Amz-Expires=43199&X-Amz-Credential=ASIASUFABKD3CGI3LJWK%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 -X GET "https://public-api.mx.clara.com/api/v3/transactions/47f8ed9e-4d7b-450b-ad6a-f1d83e3ce4e1/invoices" \
     -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

{
    "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": "04"
            },
            "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

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

NameTypeRequiredDescription
uuidstring✅ YesUUID of the transaction

🧾 Query Parameters (Optional)

NameTypeDescription
pageintegerPage index, zero-based. Default: 0
sizeintegerItems per page. Default: 20
uuiduuidFilter by extracted document UUID
typeenumFilter by document type: MEXICAN_FISCAL_INVOICE, INVOICE, RECEIPT, OTHER
validationStatusenumFilter 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:

Example Document Object

{
  "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

StatusDescription
VALIDATED_BY_CLARAAutomatically validated successfully
VALIDATED_BY_USERValidated manually by a user
NOT_VERIFIEDDocument could not be validated

☑️ Successful Response

StatusMeaning
200OK - List of extracted documents returned

❌ Error Responses

StatusMeaning
400Bad Request
401Unauthorized
403Forbidden

📘 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.