In the new version 3 of the Transactions API, Clara provides real-time card transaction processing through a paged RESTful API.
How long it take for my purchase to be in the API?
Generally, when a transaction is performed, it appears almost instantly in our API. However, there are cases where the transaction will only be recorded during the reconciliation process with our partner, Mastercard. During this process, pre-authorized transactions are converted into fully authorized transactions. The reconciliation process for a transaction may take up to 2 business days to complete.
Types of transactions
- PURCHASE: This refers to a transaction where the cardholder purchases a product or service from a merchant.
- REFUND: A refund transaction occurs when a merchant returns an amount to the cardholder, usually due to a product return or an error in processing the purchase.
- FEE: A fee is an additional charge applied to a transaction. It could be a service fee, an administrative fee, or another cost associated with using Clara's services.
- CREDIT: A credit transaction increases the cardholder's available balance. It can occur when Clara adds funds to the customer's account, such as a refund, adjustment, or reward bonus.
- PAYMENT: A payment refers to paying an outstanding amount, such as a credit card bill, a debt, or any other financial obligation.
The life cycle of a transaction
Transactions can have different statuses, which may change throughout the transaction cycle. A "NOTIFICATION" transaction is initially recorded when a purchase occurs. Then, after the first confirmation from the card issuer, it changes to a "PRE_AUTHORIZED" status. Finally, after the reconciliation process between Clara and Mastercard, the transaction is marked as "AUTHORIZED."
In addition to this cycle, other transaction statuses are immutable: REJECTED and SYSTEM_TRANSACTION. A Rejected status occurs when a purchase is canceled or cannot be completed. System Transactions are specific statuses assigned to transactions of type FEE, PAYMENT, or CREDIT.
- NOTIFICATION (ON): The initial status is recorded when a purchase is initiated.
- PRE_AUTHORIZED(AU) - PENDING: After the first confirmation from the card issuer (usually validating that the card is active and has available credit), the transaction moves to the Pre-authorized status.
- AUTHORIZED (OP): This status is assigned after Clara and Mastercard reconcile the transaction. Once the transaction is confirmed and the payment has been completed, it is marked as Authorized.
- REJECTED (RJ): The Rejected status is applied when a transaction is canceled or cannot be processed for any reason.
- SYSTEM_TRANSACTION (EC): The System Transaction status is used for transactions related to Fees, Payment, or Credit transactions.
Pagination settings
In this new version, pagination supports a maximum of 100 transactions per page and also includes filters and sorting options.
An example in how to get a single transaction from the Transactions API and it's response.
`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 the 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 will show a value of true, followed by a link. This link is the endpoint to access the download URLs for the attachments, these URLs to download the files have a lifetime of 12 hours.
The URL follows this structure: it begins with Clara's API base URL, followed by the version (in this case, version 3), the transactions endpoint, the unique identifier for the transaction, and finally, the word "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"
}
}
]
}
How to retrieve invoice information?
Clara also provides a space to upload invoice XML files, available only in Mexico. Similar to attachments, if a transaction has an invoice, the "hasInvoice" field will be marked as true, followed by a link to access the invoice.
The URL follows this structure: it begins with Clara's API base URL, followed by the version (in this case, version 3), the transactions endpoint, the unique identifier for the transaction, and finally, the word "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.