Skip to main content

​
Endpoint

POST /api/reservations/payment
Note: This endpoint is under the /api/reservations path, not /api/payments, as it’s part of the reservation creation flow.

​
Description

Generates a payment preference (e.g., for MercadoPago) based on reservation information. This preference is used to initiate the payment process with external payment providers. See implementation in server/src/modules/reservations/reservations.controller.ts:58-68.

​
Authentication

This endpoint requires Bearer token authentication. Include your access token in the Authorization header.

​
Request Body

Provide reservation information to generate the payment preference.
​
client_id
string
required
ID of the client making the reservation
​
professional_id
string
required
ID of the professional
​
start_time
string
required
Start time of the reservation in ISO 8601 format
​
end_time
string
required
End time of the reservation in ISO 8601 format
​
session_modality
string
required
Type of session: Virtual, Presencial, or empty string
​
deposit_amount
number
required
Amount to charge for the reservation deposit

​
Response

Returns a payment preference object from the payment provider (structure depends on the provider, typically MercadoPago).
​
id
string
Payment preference ID from the provider
​
init_point
string
URL where the user should be redirected to complete payment
​
sandbox_init_point
string
URL for testing in sandbox environment

​
Example Request

curl -X POST https://your-domain.com/api/reservations/payment \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "client_id": "abc123",
    "professional_id": "prof456",
    "start_time": "2026-03-15T10:00:00Z",
    "end_time": "2026-03-15T11:00:00Z",
    "session_modality": "Virtual",
    "deposit_amount": 5000
  }'

​
Example Response

{
  "id": "123456789-abcd-1234-5678-abcdef123456",
  "init_point": "https://www.mercadopago.com.ar/checkout/v1/redirect?pref_id=123456789-abcd",
  "sandbox_init_point": "https://sandbox.mercadopago.com.ar/checkout/v1/redirect?pref_id=123456789-abcd",
  "date_created": "2026-03-10T08:30:00.000Z",
  "operation_type": "regular_payment",
  "additional_info": "Reservation deposit"
}

​
Error Responses

​
Bad Request

{
  "statusCode": 400,
  "message": "Error al crear la preferencia de pago",
  "error": "Bad Request"
}

​
Unauthorized

{
  "statusCode": 401,
  "message": "Token inválido o expirado",
  "error": "Unauthorized"
}

​
Workflow

1

Create Preference

Call this endpoint with reservation details to generate a payment preference
2

Redirect User

Redirect the user to the init_point URL to complete payment with the provider
3

Process Payment

User completes payment on the provider’s site (e.g., MercadoPago)
4

Handle Callback

Payment provider sends callback with payment result and payment ID
5

Create Reservation

Call Create With Payment with the payment information to finalize the reservation

​
Integration Notes

​
MercadoPago Integration

This endpoint integrates with MercadoPago’s preference API. The service layer handles:
  • Creating the preference with MercadoPago
  • Setting callback URLs for success/failure
  • Including reservation metadata
  • Configuring payment methods

​
Payment Amount

The deposit_amount should match the professional’s configuration:
  • Check Professional Settings for the required deposit_amount
  • Ensure the amount matches to avoid discrepancies

​
Testing

For testing:
  • Use sandbox_init_point instead of init_point
  • Use MercadoPago test credentials and test cards
  • Payment provider typically offers a sandbox environment

​
Best Practices

  • Always validate the deposit amount against professional settings
  • Store the preference ID for reference
  • Implement proper error handling for payment failures
  • Set appropriate success and failure callback URLs
  • Display clear payment instructions to users
  • Handle edge cases (payment timeout, cancellation, etc.)

​
Security

  • Never expose your payment provider’s secret keys
  • Validate all callback data from the payment provider
  • Use HTTPS for all payment-related operations
  • Implement webhook verification for payment notifications

Build docs developers (and LLMs) love

Get started for freeTalk to us