Welcome to the thrilling journey with Cobre, the Money Movement platform available across various geographies!Cobre Platform offers payments products through APIs. These products are accessible via straightforward endpoints, enabling clients with seamless payment functionalities. Cobre handles all the complexities of payment processing, freeing clients from the intricacies of money movement operations.Connect with our Business Development team today to unlock your access to Cobre Platform. We're eager to connect with you and start this remarkable journey together!API Security#
At Cobre, we prioritize making security seamless and accessible. Obtaining and using our API keys is designed to be straightforward, ensuring you can securely integrate and operate with our platform from the get-go. Every API request is required to be made through the robust HTTPS protocol. This commitment not only establishes a secure environment for all your transactions but also effortlessly safeguards against the vulnerabilities of outdated HTTP requests. With Cobre, you experience the pinnacle of security with the utmost ease.Cobre strongly advise to consider taking the following security measures when integrating our APIs:• Store API credentials in a secure location - e.g., a vault (e.g., Hashicorp Vault, CyberArk, AWS Secrets Manager)
• Rotate API secrets frequently (Recommendation - once a month)
• Configure API Whitelisting on both sides (Client and Cobre)Cobre IPs: 50.17.12.196, 54.173.144.191
To configure Client IPs, a ticket must be sent to soporte@cobre.co
• Configure Secure Key for Webhooks
• Separate the Dev/Test and Production environments to segregate access - Cobre offers independent environments to facilitate this separation. Dates and Datetimes (UTC): Mastering Time Zones#
Cobre utilizes the universal UTC timezone for all date and datetime fields within our platform, offering a unified experience of time. This approach ensures that irrespective of where our clients are based, the timing of transactions and operations remains consistent and synchronized.Examples#
UTC Timestamp: "2023-07-15T12:00:00Z"In Colombia (UTC-5), this timestamp translates to July 15th, 2023, at 7:00 AM.
In Mexico City (UTC-6 during Standard Time), this represents July 15th, 2023, at 6:00 AM.
UTC Timestamp: "2023-11-10T18:30:00Z"In Colombia (UTC-5), this corresponds to November 10th, 2023, at 1:30 PM.
In Mexico City (UTC-6 during Standard Time), this means November 10th, 2023, at 12:30 PM or 1:30 PM depending on the daylight saving schedule.
total_items (number): The total number of items returned by the API.
total_pages (number): The number of pages given the current page size.
is_last_page (boolean): A true/false indicator showing whether the current page is the last page. Default: false.
page_items (number): The number of items in the current page. Default: 50.
page_size (number): You can set the maximum number of items in a page.
page_number (number): You can select the page.
contents (array): An array containing the items of the current page.
Keep in mind that it is not possible to paginate more than 10,000 records.
Rate Limit#
Cobre's public API supports 30 transactions per second (TPS) under steady-state operation. To ensure consistent performance and avoid HTTP 429 (Too Many Requests) errors, we strongly recommend following these API best practices:Implement exponential backoff with retry logic.
Use idempotency keys on all sensitive operations.
Avoid aggressive polling patterns.
Optimize request frequency and batching where applicable.
Rely on Webhooks for asynchronous updates whenever possible.
Burst Limit#
In addition to the sustained rate limit, each client's API key has a burst limit of 200 requests, implemented using a token bucket algorithm. This bucket holds up to 200 tokens (one per request) and refills at a rate of 30 tokens per second — matching the steady-state rate limit.That 200-request allowance is a one-time buffer, not a repeatable per-second cap. Once consumed, it only refills at 30 tokens/second, so sustained traffic above 30 TPS will deplete the bucket and eventually trigger HTTP 429 responses.
For example: if you fire 100 requests in the first second while the bucket is full, all 100 succeed and the bucket refills by 30 (now at 130/200). But if you sustain 50 requests/second continuously, the 200-token buffer depletes within roughly a few seconds, after which excess requests are throttled to the 30 TPS refill rate until your request volume normalizes.
Important: Because all credentials under a single client share one underlying API key, creating multiple credentials (e.g., for different services or use cases) does not increase available throughput.
Smoothing request distribution — spread requests evenly over time rather than sending them in large batches.
Implementing a token bucket or leaky bucket algorithm on your side — these patterns naturally absorb bursts while respecting rate boundaries.
Monitoring 429 responses proactively — treat them as a signal to back off immediately and retry with exponential delay.
Avoiding synchronized retries — if multiple processes retry simultaneously after a failure, it can amplify the burst. Add jitter to retry intervals.
API Conventions#
Idempotency#
Money movement and Cross Border Money Movement POST requests require an idempotency header to prevent duplicate operations on retry. If the same key is received again, Cobre returns the original response without re-executing the operation.| Rule | Detail |
|---|
| Required on | /v1/money_movements, /v1/cross_border_money_movements |
| Method | POST |
| Minimum length | 9 characters |
| Missing header | Returns HTTP 400 |
Amounts#
All monetary amounts in Cobre's API are expressed in the smallest unit of the currency (minor units).| Currency | Smallest unit | Amount | API Value |
|---|
| COP | cents | $1.500,20 COP | 150020 |
| MXN | cents | $2.390,15 MXN | 239015 |
| USD | cents | $1.52 USD | 152 |
This applies consistently across all endpoints — money movements, balances, transactions, and FX quotes. 