Saltar al contenido principal

Requisitos Previos

Para integrar la API de Dodo Payments, necesitarás:
  • Una cuenta de comerciante de Dodo Payments
  • Credenciales de API (clave de API y clave secreta de webhook) desde el panel de control

Configuración del Panel de Control

  1. Navega al Panel de Control de Dodo Payments
  2. Crea un producto (pago único o suscripción)
  3. Genera tu clave de API:
    • Ve a Desarrollador > API
    • Guía Detallada
    • Copia la clave de API en la variable de entorno llamada DODO_PAYMENTS_API_KEY
  4. Configura los webhooks:
    • Ve a Desarrollador > Webhooks
    • Crea una URL de webhook para notificaciones de pago
    • Copia la clave secreta de webhook en la variable de entorno

Integración

Enlaces de Pago

Elige la ruta de integración que se ajuste a tu caso de uso:
  • Sesiones de Pago (recomendado): Mejor para la mayoría de las integraciones. Crea una sesión en tu servidor y redirige a los clientes a un pago seguro y alojado.
  • Pago Superpuesto (embebido): Úsalo cuando necesites una experiencia en la página que embeba el pago alojado en tu sitio.
  • Enlaces de Pago Estáticos: URLs instantáneamente compartibles sin código para una rápida recolección de pagos.
  • Enlaces de Pago Dinámicos: Enlaces creados programáticamente. Sin embargo, se recomiendan las Sesiones de Pago, ya que ofrecen más flexibilidad.

1. Sesiones de Pago

Utiliza las Sesiones de Pago para crear una experiencia de pago segura y alojada para pagos únicos o suscripciones. Creas una sesión en tu servidor, luego rediriges al cliente a la checkout_url devuelta.
Las sesiones de pago son válidas por 24 horas por defecto. Si pasas confirm=true, las sesiones son válidas por 15 minutos y se deben proporcionar todos los campos requeridos.
1

Crear una sesión de pago

Elige tu SDK preferido o llama a la API REST.
import DodoPayments from 'dodopayments';

const client = new DodoPayments({
  bearerToken: process.env.DODO_PAYMENTS_API_KEY,
  environment: 'test_mode', // defaults to 'live_mode'
});

const session = await client.checkoutSessions.create({
  product_cart: [{ product_id: 'prod_123', quantity: 1 }],
  customer: { email: '[email protected]', name: 'John Doe' },
  return_url: 'https://yourapp.com/checkout/success',
});
2

Redirigir al cliente al pago

Después de crear la sesión, redirige a la checkout_url para iniciar el flujo alojado.
// Example in a browser context
window.location.href = session.checkout_url;
Prefiere las Sesiones de Pago para la forma más rápida y confiable de comenzar a aceptar pagos. Para personalización avanzada, consulta la guía completa de Sesiones de Pago y la Referencia de API.

2. Pago Superpuesto

Para una experiencia de pago en página sin interrupciones, explora nuestra integración de Pago Superpuesto que permite a los clientes completar pagos sin salir de tu sitio web.

3. Enlaces de Pago Estáticos

Los enlaces de pago estáticos te permiten aceptar pagos rápidamente compartiendo una URL simple. Puedes personalizar la experiencia de pago pasando parámetros de consulta para prellenar detalles del cliente, controlar campos del formulario y agregar metadatos personalizados.
1

Construir tu enlace de pago

Comienza con la URL base y agrega tu ID de producto:
https://checkout.dodopayments.com/buy/{productid}
2

Agregar parámetros principales

Incluye parámetros de consulta esenciales:
  • quantity
    integer
    default:"1"
    Número de artículos a comprar.
  • redirect_url
    string
    required
    URL a redirigir después de completar el pago.
La URL de redirección incluirá detalles de pago como parámetros de consulta, por ejemplo:
https://example.com/?payment_id=pay_ts2ySpzg07phGeBZqePbH&status=succeeded
3

Prellenar información del cliente (opcional)

Agrega campos de cliente o facturación como parámetros de consulta para agilizar el pago.
  • fullName
    string
    Nombre completo del cliente (ignorado si se proporciona firstName o lastName).
  • firstName
    string
    Nombre del cliente.
  • lastName
    string
    Apellido del cliente.
  • email
    string
    Dirección de correo electrónico del cliente.
  • country
    string
    País del cliente.
  • addressLine
    string
    Dirección de la calle.
  • city
    string
    Ciudad.
  • state
    string
    Estado o provincia.
  • zipCode
    string
    Código postal/ZIP.
  • showDiscounts
    boolean
    true o false
4

Controlar campos del formulario (opcional)

Puedes deshabilitar campos específicos para que sean de solo lectura para el cliente. Esto es útil cuando ya tienes los detalles del cliente (por ejemplo, usuarios que han iniciado sesión).
Para deshabilitar un campo, proporciona su valor y establece la bandera correspondiente disable… en true:
&[email protected]&disableEmail=true
CampoBandera de DesactivaciónParámetro Requerido
Nombre CompletodisableFullNamefullName
NombredisableFirstNamefirstName
ApellidodisableLastNamelastName
CorreodisableEmailemail
PaísdisableCountrycountry
Línea de DireccióndisableAddressLineaddressLine
CiudaddisableCitycity
EstadodisableStatestate
Código PostaldisableZipCodezipCode
Deshabilitar campos ayuda a prevenir cambios accidentales y asegura la consistencia de los datos.
Establecer showDiscounts=false deshabilitará y ocultará la sección de descuentos en el formulario de pago. Usa esto si deseas evitar que los clientes ingresen códigos de cupón o promoción durante el pago.
5

Agregar controles avanzados (opcional)

  • paymentCurrency
    string
    Especifica la moneda de pago. Por defecto, es la moneda del país de facturación.
  • showCurrencySelector
    boolean
    default:"true"
    Mostrar u ocultar el selector de moneda.
  • paymentAmount
    integer
    Monto en centavos (solo para precios de Paga lo que quieras).
  • metadata_*
    string
    Campos de metadatos personalizados (por ejemplo, metadata_orderId=123).
6

Compartir el enlace

Envía el enlace de pago completado a tu cliente. Cuando lo visiten, todos los parámetros de consulta se recopilan y se almacenan con un ID de sesión. La URL se simplifica para incluir solo el parámetro de sesión (por ejemplo, ?session=sess_1a2b3c4d). La información almacenada persiste a través de las actualizaciones de página y es accesible durante todo el proceso de pago.
La experiencia de pago del cliente ahora está optimizada y personalizada según tus parámetros.

4. Enlaces de Pago Dinámicos

Prefiere las Sesiones de Pago para la mayoría de los casos de uso, ofrecen más flexibilidad y control.
Creado a través de una llamada a la API o nuestro SDK con detalles del cliente. Aquí hay un ejemplo: Hay dos APIs para crear enlaces de pago dinámicos: La guía a continuación es para la creación de enlaces de pago únicos. Para instrucciones detalladas sobre la integración de suscripciones, consulta esta Guía de Integración de Suscripciones.
Asegúrate de pasar payment_link = true para obtener el enlace de pago
import DodoPayments from 'dodopayments';

const client = new DodoPayments({
bearerToken: process.env['DODO_PAYMENTS_API_KEY'], // This is the default and can be omitted
environment: 'test_mode', // defaults to 'live_mode'
});

async function main() {
const payment = await client.payments.create({
payment_link: true,
billing: { city: 'city', country: 'AF', state: 'state', street: 'street', zipcode: 0 },
customer: { email: '[email protected]', name: 'name' },
product_cart: [{ product_id: 'product_id', quantity: 0 }],
});

console.log(payment.payment_id);
}

main();
Después de crear el enlace de pago, redirige a tus clientes para completar su pago.

Implementación de Webhooks

Configura un endpoint de API para recibir notificaciones de pago. Aquí hay un ejemplo usando Next.js:
import { Webhook } from "standardwebhooks";
import { headers } from "next/headers";
import { WebhookPayload } from "@/types/api-types";

const webhook = new Webhook(process.env.DODO_WEBHOOK_KEY!); // Replace with your secret key generated from the Dodo Payments Dashboard

export async function POST(request: Request) {
  const headersList = headers();
  const rawBody = await request.text();

  const webhookHeaders = {
    "webhook-id": headersList.get("webhook-id") || "",
    "webhook-signature": headersList.get("webhook-signature") || "",
    "webhook-timestamp": headersList.get("webhook-timestamp") || "",
  };

  await webhook.verify(rawBody, webhookHeaders);
  const payload = JSON.parse(rawBody) as WebhookPayload;
  
  // Process the payload according to your business logic
}
Nuestra implementación de webhook sigue la especificación de Webhooks Estándar. Para definiciones de tipos de webhook, consulta nuestra Guía de Eventos de Webhook. Puedes consultar este proyecto con implementación de demostración en GitHub usando Next.js y TypeScript. Puedes ver la implementación en vivo aquí.