YoPlanning Payment Manager — API Documentation

POST /api/create-payment

Crea un enlace de pago (Stripe) y devuelve una URL a la que redirigir al cliente.

URL base: https://payment.yoplanning.pro

---

Autenticación

El gestor de pagos utiliza una autenticación basada en tokens, independiente del token principal de la API de YoPlanning.

Authorization: Token <PAYMENT_MANAGER_TOKEN>
Content-Type: application/json

Importante: El token del Administrador de pagos no es el mismo que el token de la API de YoPlanning v3.1. Son dos tokens distintos. Usar el incorrecto devolverá el error 401 "Token no válido".

Simbólico	Utilizado para	Dónde encontrarlo
Token de API de YoPlanning	yoplanning.pro/api/v3.1/* (disponibilidad, pedidos, etc.)	Oficina administrativa > API > Tokens
Token del gestor de pagos	payment.yoplanning.pro/api/*	Oficina administrativa > Configuración de pago > Token de API

---

Pedido

POST https://payment.yoplanning.pro/api/create-payment
Authorization: Token <PAYMENT_MANAGER_TOKEN>
Content-Type: application/json

Parámetros corporales

Campo	Requerido	Amable	Descripción
order_id	Sí	cadena	Su identificador de pedido (es decir, el UUID devuelto por /order-typicalvalidation)
vendor_id	Sí	cadena (UUID)	Tu identificador de proveedor (que encontrarás en la configuración de pagos de YoPlanning)
precio	Sí	número	Importe total en la unidad monetaria principal (por ejemplo, 196,00 para 196 euros). No en céntimos.
moneda	Sí	cadena	Código de moneda ISO 4217 (por ejemplo, "EUR", "USD")
callback_url	Sí	cadena (URL)	URL de notificación IPN: debe ser de acceso público. Se invoca mediante POST cuando se completa el pago.
url_de_redirección	No	cadena (URL)	¿Dónde redirigir al cliente después de un pago exitoso?
cancel_url	No	cadena (URL)	¿Dónde redirigir al cliente si cancela?
correo_electrónico_del_pagador	No	cadena	Rellena automáticamente el campo de correo electrónico en la página de pago.
nombre_del_titular_de_la_tarjeta	No	cadena	Rellena automáticamente el nombre del titular de la tarjeta.
apellido_del_titular_de_la_tarjeta	No	cadena	Rellena automáticamente el apellido del titular de la tarjeta.
línea_de_dirección_de_facturación1	No	cadena	Línea 1 de la dirección de facturación
línea_de_dirección_de_facturación2	No	cadena	Línea 2 de la dirección de facturación
ciudad_dirección_facturación	No	cadena	Ciudad
código postal de la dirección de facturación	No	cadena	Código Postal
país_de_facturación	No	cadena	País
billing_address_state	No	cadena	Estado/Región

Notas importantes

• El campo se llama price, no amount. Enviar amount en lugar de price dará como resultado un 500 Internal Server Error porque el servidor recibe price=None.

• El precio está en euros (o en su moneda), no en céntimos. Envíe 196,00, no 19600.

• callback_url es obligatorio, incluso si no procesas activamente las notificaciones IPN. Si lo omites, se producirá un error de validación.

• El gestor de pagos es un servicio de enlace de pago fijo: toma el precio total, no el desglose de los artículos. Los artículos del pedido pertenecen a la API de reservas de YoPlanning (/order-validation), no a este servicio.

---

Respuesta

Éxito (200)

{
  "success": true,
  "payment_id": "179384e3-4e32-4f03-b6ea-2fdc998e2c6c",
  "customer_id": null,
  "vakario_fee": "0.00",
  "payment_solution": "Stripe",
  "payment_url": "https://payment.yoplanning.pro/pay/8edf6170-5495-432d-8b04-6717ccb8ad68"
}

Campo	Amable	Descripción
éxito	booleano	true si se creó el enlace de pago
payment_id	cadena (UUID)	identificador de pago único
customer_id	cadena o nulo	Identificación del cliente si se reconoce
vakario_fee	cadena	Tarifa de la plataforma (cadena decimal)
solución_de_pago	cadena	Proveedor de pago utilizado (“Stripe”)
url_de_pago	cadena (URL)	Redirigir al cliente a esta URL para completar el pago

Error de validación (400)

{
  "success": false,
  "errors": {
    "callback_url": ["This field is required."]
  }
}

Error de autenticación (401)

No hay encabezado Authorization:

{"detail": "Authentication credentials were not provided."}

Token incorrecto (por ejemplo, usar el token de la API de YoPlanning en lugar del token del Administrador de pagos):

{"detail": "Invalid token."}

Error del servidor (500)

Devuelve una página de error HTML (no JSON) con el mensaje "La plataforma de pago está temporalmente fuera de servicio."

Esto no es una interrupción real de la plataforma. En la práctica, los errores 500 son causados ​​por:

Causa principal	Error del servidor	Arreglar
El campo price no está presente o es null.	TypeError: '>' no es compatible entre instancias de 'NoneType' e 'int' en checkPaymentSolution	Asegúrese de que price sea un número en el cuerpo JSON. El campo se llama price, no amount.
vendor_id falta o es inválido.	Varios errores de formulario de Django	Asegúrese de que vendor_id sea una cadena UUID válida.

La respuesta 500 devuelve HTML, no JSON. Analice la respuesta con precaución si espera JSON.

---

Devolución de llamada IPN

Cuando se completa el pago (o falla), el Administrador de pagos envía una solicitud POST a su callback_url:

{
  "success": true,
  "payed": true,
  "order_id": "your-order-id",
  "payment_solution": "Stripe",
  "payer_lang": "fr"
}

Campo	Amable	Descripción
éxito	booleano	Si el pago se realizó correctamente
pagado	booleano	Si el pago fue cobrado
order_id	cadena	El order_id que proporcionaste al crear el pago
solución_de_pago	cadena	Proveedor utilizado
payer_lang	cadena	Idioma del navegador del pagador

Requisitos para callback_url:

• Debe ser de acceso público (sin autenticación).

• Debe aceptar solicitudes POST

• Debe devolver un código de estado 2xx.

---

Ejemplo completo

rizo

curl -X POST "https://payment.yoplanning.pro/api/create-payment" \
  -H "Authorization: Token YOUR_PAYMENT_MANAGER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "order_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "vendor_id": "your-vendor-uuid",
    "price": 196.00,
    "currency": "EUR",
    "payer_email": "[email protected]",
    "cardholder_first_name": "Jean",
    "cardholder_last_name": "Dupont",
    "callback_url": "https://yoursite.com/api/payment-callback",
    "redirection_url": "https://yoursite.com/confirmation?status=success",
    "cancel_url": "https://yoursite.com/confirmation?status=cancelled"
  }'

JavaScript (obtener)

const response = await fetch('https://payment.yoplanning.pro/api/create-payment', {
  method: 'POST',
  headers: {
    'Authorization': 'Token YOUR_PAYMENT_MANAGER_TOKEN',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    order_id: orderId,
    vendor_id: 'your-vendor-uuid',
    price: 196.00,       // euros, NOT cents
    currency: 'EUR',
    payer_email: '[email protected]',
    callback_url: 'https://yoursite.com/api/payment-callback',
    redirection_url: 'https://yoursite.com/confirmation?status=success',
    cancel_url: 'https://yoursite.com/confirmation?status=cancelled',
  }),
});
​
const data = await response.json();
​
if (data.success && data.payment_url) {
  // Redirect customer to payment page
  window.open(data.payment_url, '_blank');
}

Python (solicitudes)

import requests
​
response = requests.post(
    "https://payment.yoplanning.pro/api/create-payment",
    headers={
        "Authorization": "Token YOUR_PAYMENT_MANAGER_TOKEN",
        "Content-Type": "application/json",
    },
    json={
        "order_id": order_id,
        "vendor_id": "your-vendor-uuid",
        "price": 196.00,
        "currency": "EUR",
        "payer_email": "[email protected]",
        "callback_url": "https://yoursite.com/api/payment-callback",
        "redirection_url": "https://yoursite.com/confirmation?status=success",
        "cancel_url": "https://yoursite.com/confirmation?status=cancelled",
    },
)
​
data = response.json()
payment_url = data.get("payment_url")

---

Flujo de integración típico

1. Customer selects dates and products
         │
         ▼
2. Check availability
   GET yoplanning.pro/api/v3.1/teams/{team}/online-products/{product}/availabilities/
         │
         ▼
3. Validate the order
   POST yoplanning.pro/api/v3.1/teams/{team}/order-validation
   → Returns order ID
         │
         ▼
4. Create payment link
   POST payment.yoplanning.pro/api/create-payment
   → Returns payment_url
         │
         ▼
5. Redirect customer to payment_url (Stripe checkout)
         │
         ▼
6. Customer pays → redirected to redirection_url
   Payment Manager POSTs to callback_url (IPN)

---

CORS

La API del Administrador de Pagos no devuelve encabezados CORS. Las llamadas directas desde un navegador serán bloqueadas por la política de mismo origen del navegador.

Soluciones:

• Utilice un proxy del lado del servidor (por ejemplo, Cloudflare Worker, backend de Node.js, función sin servidor) para reenviar las solicitudes.

• Llama a la API desde tu backend, no desde JavaScript del lado del cliente.

---

Preguntas frecuentes

P: Recibo el error 401 "Token no válido", pero mi token funciona en la API de YoPlanning. R: El Administrador de pagos tiene su propio token, distinto del token de la API de YoPlanning v3.1. Verifica la configuración de pagos en el panel de administración para asegurarte de tener el token correcto.

P: Recibo una página de error HTML 500 en lugar de JSON. R: Esto casi siempre significa que falta un campo obligatorio o que es null. Compruebe que price (no amount) sea un número en el cuerpo de su solicitud. Verifique también que vendor_id esté presente y sea válido.

P: Mi callback_url aún no es accesible. ¿Puedo omitirlo? R: No, callback_url es obligatorio. Puedes indicarle una URL de marcador de posición que devuelva 200, pero el campo debe estar presente.

P: ¿Necesito pasar los detalles de las líneas de pedido al Administrador de pagos? R: No. El Administrador de pagos solo gestiona el pago; recibe un precio fijo. Los detalles de las líneas pertenecen a la API de pedidos de YoPlanning (/order-validation).

P: ¿El precio está en centavos o en la unidad monetaria principal de la divisa? R: En la unidad monetaria principal. Para euros, envíe 196,00, no 19600.