Venflow API
V1Payment links

Crear un payment link

POST
/v1/payment-links

Authorization

Api-Key<token>

Tu clave API privada (comienza con pvk_)

In: header

Organization<token>

Tu ID de organización

In: header

Request Body

active?boolean

Si el link queda activo al crearse (predeterminado: true)

allow_manual_payments?boolean

Si es false, se oculta y bloquea el pago manual ("Otros Bancos"). Predeterminado: true.

En planes de pago único debe quedar en true: Débito Inmediato es su único medio de pago

apply_discount_to_additional_items?boolean

Determina si el descuento aplica también a los items adicionales. Predeterminado: true

collection_mode?string

Quién decide cuándo se cobran las suscripciones que genere el link (opcional, predeterminado: engine).

engine: Venflow las cobra automáticamente en cada ciclo. external (Cobro por API): el checkout registra la domiciliación y Venflow nunca cobra solo; cada cobro lo pides tú con POST /v1/subscriptions/{id}/charges. No se puede cambiar después de crear el link.

external debe estar habilitado para tu organización y requiere un plan recurrente y items que no sean por uso (metered). Con external, el trial del plan no aplica; enviar trial_days mayor que 0 o allow_manual_payments: true devuelve 400

Value in"engine" | "external"
discount_id?string

ID de un descuento existente que se aplica a cada sesión del link (opcional)

Formatuuid
expiration_hours?integer

Horas de vigencia de cada sesión que genere el link (1-24, predeterminado: 1)

Range1 <= value <= 24
external_initial_charge?boolean

Solo con collection_mode: "external": si es true, el checkout también cobra el primer pago; los siguientes los pides tú por API. Predeterminado: false. Enviarlo en true sin collection_mode: "external" devuelve 400

items?

Items adicionales que se cobran junto al plan. Solo items de producto (máximo 100).

Acotado a propósito: cada item es una fila permanente de la plantilla del link, que se vuelve a leer en cada consulta del recurso — a diferencia de los items de una sesión, que caducan con ella

Itemsitems <= 100
metadata?

Key-value pairs for storing your own information on this payment link. Venflow does not interpret them: they are stored and returned to you unchanged.

This metadata is copied into every checkout session the link creates, and the payment webhook reports that session's metadata — so tagging a link is how you recognise the charge it produces. The copy is taken when the link is opened: editing the link later does not change sessions that already exist. It goes no further than the session; a subscription or invoice born from it starts empty.

Four key names are reserved by Venflow and rejected: checkoutMode, subscriptionId, obInvoiceId and billing_cycles. Use a different name, such as externalId or orderRef.

At most 50 keys; keys up to 40 characters, values up to 500, and 27000 characters across all keys and values. Do not store sensitive data here: it is not encrypted and is returned on reads. Your customer's checkout page never receives it.

Propertiesproperties <= 50
planstring

ID del plan que se cobra (REQUERIDO). Acepta planes recurrentes y de pago único

Formatuuid
Length1 <= length
redirect_url?string

URL a la que se redirige al cliente después de completar el pago (opcional)

Lengthlength <= 2048
trial_days?integer

Días de prueba para las suscripciones que genere el link (0-365).

Solo para planes recurrentes; omitir para heredar los del plan

Range0 <= value <= 365

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X POST "https://api.venflow.app/v1/payment-links" \  -H "Content-Type: application/json" \  -d '{    "plan": "550e8400-e29b-41d4-a716-446655440000",    "redirect_url": "https://miapp.ejemplo.com/gracias",    "expiration_hours": 24  }'
{
  "active": true,
  "allow_manual_payments": true,
  "apply_discount_to_additional_items": true,
  "collection_mode": "engine",
  "created": 0.1,
  "discount_id": "string",
  "expiration_hours": 0.1,
  "external_initial_charge": true,
  "id": "string",
  "items": [
    {
      "id": "string",
      "name": "string",
      "plan_id": "string",
      "price": 0.1,
      "product_id": "string",
      "quantity": 0.1
    }
  ],
  "livemode": true,
  "metadata": {
    "property1": "string",
    "property2": "string"
  },
  "object": "payment_link",
  "plan": "string",
  "redirect_url": "string",
  "trial_days": 0,
  "url": "string"
}
{
  "code": "not_found",
  "details": {},
  "message": "string"
}
{
  "code": "not_found",
  "details": {},
  "message": "string"
}
{
  "code": "not_found",
  "details": {},
  "message": "string"
}
{
  "code": "not_found",
  "details": {},
  "message": "string"
}
{
  "code": "not_found",
  "details": {},
  "message": "string"
}
{
  "code": "not_found",
  "details": {},
  "message": "string"
}

Listar todos los payment links GET

Lista los payment links de tu organización, los más recientes primero, incluidos los desactivados. - Cuando `has_more` es `true`, pide la página siguiente con `starting_after` igual al `id` del último elemento que recibiste. - Los payment links no se eliminan, así que `starting_after` es la única forma de llegar a los más antiguos. Devuelve la lista de payment links de tu organización, ordenados por fecha de creación con los más recientes primero. Incluye los links desactivados, para que puedas ver cuáles apagaste. Incluye links de planes recurrentes y de pago único. Cuando `has_more` es true, pedí la página siguiente con `starting_after` igual al id del último elemento.

Obtener un payment link GET

Obtiene un payment link por su ID, esté activo o desactivado. Un link de otra organización responde 404, igual que uno que no existe. Obtiene los datos de un payment link existente, esté activo o desactivado. Sirve tanto para links de planes recurrentes como de pago único.