Skip to main content

​
POST /api/mercado-pago/create-preference

Creates a new Mercado Pago payment preference and initializes a payment record in the database. This endpoint is used when users book virtual English classes.

​
Authentication

Requires user authentication via session.

​
Request Body

​
Response

​
preferenceId
string
The Mercado Pago preference ID used to identify this payment
​
initPoint
string
The Mercado Pago checkout URL where users complete the payment

​
Payment Status Values

The payment can have one of the following statuses:
  • approved - Payment was successfully processed
  • pending - Payment is awaiting confirmation
  • rejected - Payment was declined or failed

​
Example Request

curl -X POST https://your-domain.com/api/mercado-pago/create-preference \
  -H "Content-Type: application/json" \
  -d '{
    "type": "individual",
    "studentsCount": 2,
    "price": 10
  }'

​
Example Response

{
  "preferenceId": "123456789-a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "initPoint": "https://www.mercadopago.com.ar/checkout/v1/redirect?pref_id=123456789-a1b2c3d4"
}

​
Error Responses

​
error
string
Error message describing what went wrong
401 Unauthorized 
{
  "error": "User not authenticated"
}
500 Internal Server Error 
{
  "error": "Failed to create preference"
}

{
  "error": "Failed to create payment record in our database"
}

​
Payment Configuration

The payment preference includes:
  • Installments: Up to 12 monthly installments
  • Currency: ARS (Argentine Peso)
  • Auto Return: Automatically redirects on approval
  • Callback URLs:
    • Success: /checkout/callback/success
    • Failure: /checkout/callback/failure
    • Pending: /checkout/callback/pending

​
Database Record

Creates a PaymentMercadoPago record with the following fields:
​
userId
string
ID of the authenticated user making the payment
​
preferenceId
string
Unique Mercado Pago preference identifier
​
price
number
Payment amount in ARS
​
type
string
Class type: individual or grupal
​
maxParticipants
number
Maximum number of participants for the class
​
status
string
Payment status (defaults to pending)

​
Webhook Notification

The endpoint automatically configures a webhook notification URL that Mercado Pago will call when payment status changes. See the Webhook Documentation for more details.

Build docs developers (and LLMs) love

Get started for freeTalk to us