Overview
The MercadoPago integration endpoint creates payment preferences that allow users to complete purchases through MercadoPago’s checkout system. This endpoint is implemented as a Cloudflare Worker and handles both preference creation and webhook processing.Endpoint
Authentication
This endpoint requires server-side authentication using MercadoPago credentials:- MP_ACCESS_TOKEN: MercadoPago access token (server-side only)
- NEXT_PUBLIC_MP_PUBLIC_KEY: Public key for client-side SDK initialization
Request Body
Array of items to be purchased. Each item must include:
Optional payer information
Custom redirect URLs (optional, defaults to JCV Fitness URLs)
Plan identifier for internal tracking (e.g.,
PLAN_BASICO, PLAN_PRO, PLAN_PREMIUM)User ID for associating the payment with a specific user. This is included in the
external_reference.Response
MercadoPago preference ID
URL to redirect the user for production checkout
URL to redirect the user for sandbox/test checkout
Example Request
Example Response
Payment Flow Diagram
Predefined Plans
JCV Fitness has three predefined subscription plans:Plan Basico
Price: $49,900 COP
- 7-day meal plan
- Home workout routine
- App access
- Email support
Plan Pro
Price: $89,900 COP
- Personalized meal plan
- Gym + home routines
- Exercise videos
- Priority support
- Weekly tracking
Plan Premium
Price: $149,900 COP
- Everything in Pro
- 1-on-1 coaching
- Monthly adjustments
- VIP community access
- Results guarantee
Using the Client SDK
For client-side integration, use the JCV Fitness payment utility functions:Error Handling
Error message if the request fails
Additional error details from MercadoPago
Common Errors
| Status Code | Error | Description |
|---|---|---|
| 400 | Items are required | No items provided in request |
| 401 | Authentication error | Invalid MP_ACCESS_TOKEN |
| 500 | Server configuration error | Missing environment variables |
| 500 | Failed to create preference | MercadoPago API error |
Security
CORS Protection: The Cloudflare Worker only accepts requests from approved origins:
https://jcv24fitness.comhttps://www.jcv24fitness.comhttps://*.pages.devhttp://localhost:3000(development)
Testing
Test Cards
Use these test cards in sandbox mode:| Card | Number | CVV | Expiry |
|---|---|---|---|
| Visa | 4509 9535 6623 3704 | 123 | Any future date |
| Mastercard | 5031 7557 3453 0604 | 123 | Any future date |
Sandbox Environment
To test in sandbox mode:- Use
NEXT_PUBLIC_MP_PUBLIC_KEYstarting withTEST- - Redirect users to
sandboxInitPointinstead ofinitPoint - Use test card numbers from the table above
Related Endpoints
Payment Webhook
Handle MercadoPago payment notifications