Referencia SDK JavaScript

El SDK de JavaScript de PayPal expone dinámicamente objetos y métodos basados en los componentes que seleccione. Añada componentes a su <script> pasándolos en la URL src usando el parámetro de consulta components.

Descripción general

<script src="https://www.paypal.com/sdk/js?client-id=YOUR_CLIENT_ID&components=YOUR_COMPONENTS"></script>

El SDK de JavaScript admite los siguientes componentes:

buttons (predeterminado)
marks
card-fields
funding-eligibility
messages

Importante: Esta es la versión 2 de la guía de referencia del SDK de JavaScript. Versión 1 es una integración heredada.

Botones

El componente de botones de pago muestra automáticamente todos los botones elegibles en una única ubicación en su página. Consulte la integración de pagos estándar.

<script src="https://www.paypal.com/sdk/js?client-id=YOUR_CLIENT_ID&components=buttons"></script>

import { PayPalScriptProvider, PayPalButtons } from "@paypal/react-paypal-js";

export default function App() {
    const initialOptions = {
        clientId: "YOUR_CLIENT_ID",
        // Añada otras opciones según sea necesario
    };
    
    return (
        <div className="App">
            <PayPalScriptProvider options={initialOptions}>
                <PayPalButtons />
            </PayPalScriptProvider>
        </div>
    );
}

import { PayPalButtons, PayPalScriptProvider, ReactPayPalScriptOptions } from '@paypal/react-paypal-js';

export default function App() {
    const initialOptions: ReactPayPalScriptOptions = {
        clientId: "YOUR_CLIENT_ID",
        // Añada otras opciones según sea necesario
    };

    return (
        <div className="App">
            <PayPalScriptProvider options={initialOptions}>
              <PayPalButtons />
            </PayPalScriptProvider>
        </div>
    );
}

import { loadScript } from "@paypal/paypal-js";

let paypal;

try {
    paypal = await loadScript({ clientId: "YOUR_CLIENT_ID" });
} catch (error) {
    console.error("failed to load the PayPal JS SDK script", error);
}

if (paypal) {
    try {
        await paypal.Buttons().render("#paypal-button-container");
    } catch (error) {
        console.error("failed to render the PayPal Buttons", error);
    }
}

`paypal.Buttons(options)`

style
message
createOrder
createSubscription
onApprove
onCancel
onError
onInit/onClick
onShippingChange
onShippingAddressChange
onShippingOptionsChange

Style

Personalice sus botones utilizando la opción style.

paypal.Buttons({
  style: {
    layout: 'vertical',
    color:  'blue',
    shape:  'rect',
    label:  'paypal'
  }
}).render('#paypal-button-container');


import { PayPalScriptProvider, PayPalButtons } from "@paypal/react-paypal-js";

export default function App() {
    const initialOptions = {
        clientId: "YOUR_CLIENT_ID",
    };

    const styles = {
        shape: "rect",
        layout: "vertical",
    };

    return (
        <div className="App">
            <PayPalScriptProvider options={initialOptions}>
                <PayPalButtons style={styles} />
            </PayPalScriptProvider>
        </div>
    );
}


import { PayPalButtons, PayPalButtonsComponentProps, PayPalScriptProvider, ReactPayPalScriptOptions } from '@paypal/react-paypal-js';

export default function App() {
    const initialOptions: ReactPayPalScriptOptions = {
        clientId: "YOUR_CLIENT_ID",
    };

    const styles: PayPalButtonsComponentProps["style"] = {
        shape: "rect",
        layout: "vertical",
    };

    return (
        <div className="App">
            <PayPalScriptProvider options={initialOptions}>
              <PayPalButtons style={styles}/>
            </PayPalScriptProvider>
        </div>
    );
}


import { loadScript } from "@paypal/paypal-js";

let paypal;

try {
    paypal = await loadScript({ clientId: "YOUR_CLIENT_ID" });
} catch (error) {
    console.error("failed to load the PayPal JS SDK script", error);
}

if (paypal) {
    try {
        await paypal.Buttons({
            style: {
                layout: 'vertical',
                color:  'blue',
                shape:  'rect',
                label:  'paypal'
            }
    }).render("#paypal-button-container");
    } catch (error) {
        console.error("failed to render the PayPal Buttons", error);
    }
}

Layout

Establezca la opción style.layout para determinar cómo aparecen los botones cuando hay múltiples botones disponibles:

Valor

Descripción

Diseño

vertical

Predeterminado. Los botones se apilan verticalmente con un máximo de 6 botones. Recomendado cuando:

Presenta una lista dinámica de opciones de pago en páginas de pago y carrito de compras.
Utiliza Checkout como plataforma de pagos completa.

Móvil

Venmo está disponible en móvil solo en mercados de EE.UU.

Web

horizontal

Los botones se apilan horizontalmente con un máximo de 2 botones. Recomendado cuando:

Coloca botones en una página de producto, junto al producto.
El espacio en la página es limitado.
Ya se proporcionan opciones de pago alternativas.

Móvil

Venmo está disponible en móvil solo en mercados de EE.UU.

Web

¿Qué botones veré?

Los botones que aparecen se deciden automáticamente, basándose en varios factores, incluyendo:

País del comprador
Tipo de dispositivo
Fuentes de financiación que el comprador ha optado por ver

Como resultado, cada comprador ve una combinación única de botones. Las ofertas de Pay Later varían según el país y tienen diferentes botones. Para evitar que aparezcan ciertos botones, consulte Deshabilitar financiación en la referencia del SDK de JavaScript.

Color

Establezca la opción style.color a uno de estos valores:

Valor

Descripción

Botón

gold

Recomendado

La gente de todo el mundo nos conoce por el color dorado y la investigación lo confirma. Pruebas exhaustivas determinaron el tono y la forma exactos que ayudan a aumentar la conversión. Úselo en su sitio web para aprovechar el reconocimiento y la preferencia de PayPal.

blue

Primera alternativa

Si el dorado no funciona para su sitio, pruebe el botón azul de PayPal. La investigación muestra que la gente sabe que es nuestro color de marca, lo que proporciona un halo de confianza y seguridad a su experiencia.

silver white black

Segundas alternativas

Si el dorado o el azul no funcionan para el diseño o la estética de su sitio, pruebe los botones plateado, blanco o negro. Debido a que estos colores son menos capaces de atraer la atención de la gente, recomendamos estos colores de botón como segunda alternativa.

Shape

Establezca la opción style.shape a uno de estos valores:

Valor

Descripción

Botón

rect

Recomendado

La forma de botón predeterminada.

pill

Redondea los lados del botón.

sharp

Da al botón esquinas afiladas.

borderRadius

style.borderRadius se utiliza para definir un radio de borde personalizado de los botones.

Para definir el radio del borde de los botones, establezca la opción style.borderRadius a un número que sea mayor o igual a 0.

Nota

Si se definen tanto style.borderRadius como style.shape, style.borderRadius tendrá prioridad.


paypal.Buttons({
  style: {
    borderRadius: 10,
  }
}).render('#paypal-button-container');


import { PayPalScriptProvider, PayPalButtons } from "@paypal/react-paypal-js";

export default function App() {
    const initialOptions = {
        clientId: "YOUR_CLIENT_ID",
    };

    const styles = {
        borderRadius: 10,
    };

    return (
        <div className="App">
            <PayPalScriptProvider options={initialOptions}>
                <PayPalButtons style={styles} />
            </PayPalScriptProvider>
        </div>
    );
}


import { PayPalButtons, PayPalButtonsComponentProps, PayPalScriptProvider, ReactPayPalScriptOptions } from '@paypal/react-paypal-js';

export default function App() {
    const initialOptions: ReactPayPalScriptOptions = {
        clientId: "YOUR_CLIENT_ID",
    };

    const styles : PayPalButtonsComponentProps["style"] = {
        borderRadius: 10,
    };

    return (
        <div className="App">
            <PayPalScriptProvider options={initialOptions}>
              <PayPalButtons style={styles}/>
            </PayPalScriptProvider>
        </div>
    );
}


import { loadScript } from "@paypal/paypal-js";

let paypal;

try {
    paypal = await loadScript({ clientId: "YOUR_CLIENT_ID" });
} catch (error) {
    console.error("failed to load the PayPal JS SDK script", error);
}

if (paypal) {
    try {
        await paypal.Buttons({
            style: {
                borderRadius: 10,
            }
    }).render("#paypal-button-container");
    } catch (error) {
        console.error("failed to render the PayPal Buttons", error);
    }
}

Tamaño

El botón se adapta al tamaño de su elemento contenedor por defecto.
Su elemento contenedor de botón necesita ser lo suficientemente ancho para sus botones de pago horizontales.

Height

Para personalizar la altura del botón, establezca la opción style.height a un valor entre 25 y 55. El botón tiene una altura máxima predeterminada de 55px. Elimine esta limitación y establezca la altura del botón para llenar su contenedor padre:

Establezca style.disableMaxHeight a true.
Seleccione una fuente de financiación válida: fundingSource: 'paypal' | 'venmo' | 'paylater' | 'credit'
Cambie el valor de height a nivel del contenedor padre.

Si se definen tanto style.disableMaxHeight como style.height en el botón de PayPal, se lanzará un error y el botón no se renderizará. Debe elegir uno u otro.


paypal.Buttons({
  style: {
    disableMaxHeight: true,
  }
}).render('#paypal-button-container');


import { PayPalScriptProvider, PayPalButtons } from "@paypal/react-paypal-js";

export default function App() {
    const initialOptions = {
        clientId: "YOUR_CLIENT_ID",
    };

    const styles = {
        disableMaxHeight: true,
    };

    return (
        <div className="App">
            <PayPalScriptProvider options={initialOptions}>
                <PayPalButtons style={styles} />
            </PayPalScriptProvider>
        </div>
    );
}


import { PayPalButtons, PayPalButtonsComponentProps, PayPalScriptProvider, ReactPayPalScriptOptions } from '@paypal/react-paypal-js';

export default function App() {
    const initialOptions: ReactPayPalScriptOptions = {
        clientId: "YOUR_CLIENT_ID",
    };

    const styles : PayPalButtonsComponentProps["style"] = {
        disableMaxHeight: true,
    };

    return (
        <div className="App">
            <PayPalScriptProvider options={initialOptions}>
              <PayPalButtons style={styles}/>
            </PayPalScriptProvider>
        </div>
    );
}


import { loadScript } from "@paypal/paypal-js";

let paypal;

try {
    paypal = await loadScript({ clientId: "YOUR_CLIENT_ID" });
} catch (error) {
    console.error("failed to load the PayPal JS SDK script", error);
}

if (paypal) {
    try {
        await paypal.Buttons({
            style: {
                disableMaxHeight: true,
            }
    }).render("#paypal-button-container");
    } catch (error) {
        console.error("failed to render the PayPal Buttons", error);
    }
}

Ancho

El botón tiene un ancho máximo predeterminado de 750px, pero puede hacer el botón más grande:

Establezca style.disableMaxWidth a true.
Cambie el valor de max-width a nivel del contenedor.


paypal.Buttons({
  style: {
    disableMaxWidth: true,
  }
}).render('#paypal-button-container');


import { PayPalScriptProvider, PayPalButtons } from "@paypal/react-paypal-js";

export default function App() {
    const initialOptions = {
        clientId: "YOUR_CLIENT_ID",
    };

    const styles = {
        disableMaxWidth: true,
    };

    return (
        <div className="App">
            <PayPalScriptProvider options={initialOptions}>
                <PayPalButtons style={styles} />
            </PayPalScriptProvider>
        </div>
    );
}


import { PayPalButtons, PayPalButtonsComponentProps, PayPalScriptProvider, ReactPayPalScriptOptions } from '@paypal/react-paypal-js';

export default function App() {
    const initialOptions: ReactPayPalScriptOptions = {
        clientId: "YOUR_CLIENT_ID",
    };

    const styles : PayPalButtonsComponentProps["style"] = {
        disableMaxWidth: true,
    };

    return (
        <div className="App">
            <PayPalScriptProvider options={initialOptions}>
              <PayPalButtons style={styles}/>
            </PayPalScriptProvider>
        </div>
    );
}


import { loadScript } from "@paypal/paypal-js";

let paypal;

try {
    paypal = await loadScript({ clientId: "YOUR_CLIENT_ID" });
} catch (error) {
    console.error("failed to load the PayPal JS SDK script", error);
}

if (paypal) {
    try {
        await paypal.Buttons({
            style: {
                disableMaxWidth: true,
            }
    }).render("#paypal-button-container");
    } catch (error) {
        console.error("failed to render the PayPal Buttons", error);
    }
}

Label

Establezca la opción style.label a uno de estos valores:

Valor

Descripción

Botón

paypal

Recomendado La opción predeterminada. Muestra el logo de PayPal.

checkout

Muestra el botón de Checkout.

buynow

Muestra el botón PayPal Buy Now e inicializa el flujo de pago.

pay

Muestra el botón Pay With PayPal e inicializa el flujo de pago.

installment

Muestra el botón de pago a plazos de PayPal y ofrece un número específico de pagos durante un período de pago a plazos.

La característica installment está disponible solo en MX y BR.

Establezca style.period para establecer el número de pagos durante el período de pago a plazos:

BR: 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12
en_MX, MX: 3, 6, 9, 12

Tagline

Establezca style.tagline a false para deshabilitar el texto del eslogan:

Establezca style.layout a horizontal para eslóganes. Si usa la opción message, reemplazará el eslogan.

Valor

Descripción

Botón

true

Recomendado

Mostrar texto del eslogan. Predeterminado.

Dos formas fáciles de pagar

false

Deshabilitar texto del eslogan.

Message

Personalice el mensaje con sus botones utilizando la opción message.

paypal.Buttons({
  message: {
    amount: 100,
    align: 'center',
    color: 'black',
    position: 'top',
  }
}).render('#paypal-button-container');

Amount

Establezca la opción message.amount para mostrar la oferta más relevante y el desglose de precios a sus clientes.

Para definir la cantidad del mensaje, establezca la opción message.amount a un número mayor que 0. Este valor debe reflejar el valor actual del producto o carrito que se utilizará una vez que se haya iniciado una sesión de pago.

Valor

Descripción

Mensaje

undefined

Predeterminado. Cuando no se proporciona un valor de cantidad, se muestra un mensaje genérico.

100

Un ejemplo de cantidad calificada para Pay in 4 con un desglose de cantidad semanal.

2000

Un ejemplo de cantidad calificada para Pay Monthly con un desglose de cantidad mensual.

Align

Establezca la opción message.align para alinear el contenido del mensaje con los botones.

Valor

Descripción

Mensaje

center

Predeterminado. Alineado en el centro entre los bordes de los botones.

left

Alineado al borde izquierdo de los botones.

right

Alineado al borde derecho de los botones.

Color

Establezca la opción message.color para cambiar el color del mensaje de negro o blanco dependiendo del fondo de su sitio web para que el mensaje sea visible.

Valor

Descripción

Mensaje

black

Predeterminado. Texto negro con un logo de PayPal coloreado y texto de enlace azul.

white

Texto blanco con un logo de PayPal blanco y texto de enlace blanco.

Position

Establezca la opción message.position para colocar el mensaje encima o debajo de los botones.

Valor

Descripción

Mensaje

top

Posicionar el mensaje encima de los botones.

bottom

Predeterminado. Posicionar el mensaje debajo de los botones. Nota: Cuando el botón de Tarjeta de Débito/Crédito está presente como parte de su pila de botones, solo se admite top y será el valor predeterminado.

displayOnly

El parámetro displayOnly determina los métodos de pago que ven sus clientes. Por defecto, los compradores ven todos los métodos de pago elegibles. Las opciones pasadas a displayOnly se aplican en orden de izquierda a derecha.

Tenemos las siguientes opciones disponibles:

Valor

Descripción

vaultable

Mostrar solo los métodos de pago que admiten guardar. Su integración, configuración de comerciante y ubicación del cliente determinan qué métodos de pago se pueden guardar.

paypal.Buttons({
  displayOnly: ["vaultable"]
}).render('#paypal-button-container');

import { PayPalScriptProvider, PayPalButtons } from "@paypal/react-paypal-js";

export default function App() {
  const initialOptions = {
    clientId: "YOUR_CLIENT_ID",
  };

  const displayOnly = ["vaultable"];

  return (
    <div className="App">
      <PayPalScriptProvider options={initialOptions}>
        <PayPalButtons displayOnly={displayOnly} />
      </PayPalScriptProvider>
    </div>
  );
}

import { PayPalButtons, PayPalButtonsComponentProps, PayPalScriptProvider, ReactPayPalScriptOptions } from '@paypal/react-paypal-js';

export default function App() {
  const initialOptions: ReactPayPalScriptOptions = {
    clientId: "YOUR_CLIENT_ID",
  };

  const displayOnly: PayPalButtonsComponentProps["displayOnly"] = ["vaultable"];

  return (
    <div className="App">
      <PayPalScriptProvider options={initialOptions}>
        <PayPalButtons displayOnly={displayOnly} />
      </PayPalScriptProvider>
    </div>
  );
}

import { loadScript } from "@paypal/paypal-js";

let paypal;

try {
  paypal = await loadScript({ clientId: "YOUR_CLIENT_ID" });
} catch (error) {
  console.error("failed to load the PayPal JS SDK script", error);
}

if (paypal) {
  try {
    await paypal.Buttons({
      displayOnly: ["vaultable"],
    }).render("#paypal-button-container");
  } catch (error) {
    console.error("failed to render the PayPal Buttons", error);
  }
}

createOrder

La función createOrder configura los detalles de la transacción. Pase createOrder como parámetro en paypal.Buttons(). Cuando el comprador selecciona el botón de PayPal, createOrder inicia la ventana de PayPal Checkout. El comprador inicia sesión y aprueba la transacción en el sitio web paypal.com.

<!DOCTYPE html>
<html>
  <head>
    <meta name="viewport" content="width=device-width, initial-scale=1">
  </head>
  <body>
    <!-- Configure un elemento contenedor para el botón -->
    <div id="paypal-button-container"></div>

    <script src="https://www.paypal.com/sdk/js?client-id=YOUR_CLIENT_ID&currency=USD"></script>

    <script>
      paypal.Buttons({
        async createOrder() {
          const response = await fetch("/my-server/create-paypal-order", {
            method: "POST",
            headers: {
              "Content-Type": "application/json",
            },
            body: JSON.stringify({
              cart: [{
                sku: "YOUR_PRODUCT_STOCK_KEEPING_UNIT",
                quantity: "YOUR_PRODUCT_QUANTITY",
              }]
            })
          });

          const order = await response.json();

          return order.id;
        }
      }).render('#paypal-button-container');
    </script>
  </body>
</html>

import { PayPalButtons, PayPalScriptProvider } from "@paypal/react-paypal-js";

export default function App() {
  const initialOptions = {
    clientId: "YOUR_CLIENT_ID",
  };

  const createOrder = async () => {
    try {
      const response = await fetch("/my-server/create-paypal-order", {
        method: "POST",
        headers: { "Content-Type": "application/json" },
        body: JSON.stringify({
          cart: [{ id: "YOUR_PRODUCT_ID", quantity: "YOUR_PRODUCT_QUANTITY" }],
        }),
      });

      const orderData = await response.json();

      if (!orderData.id) {
        const errorDetail = orderData.details[0];
        const errorMessage = errorDetail
          ? `${errorDetail.issue} ${errorDetail.description} (${orderData.debug_id})`
          : "Se produjo un error inesperado, por favor inténtelo de nuevo.";

        throw new Error(errorMessage);
      }

      return orderData.id;
    } catch (error) {
      console.error(error);
      throw error;
    }
  };

  return (
    <div className="App">
      <PayPalScriptProvider options={initialOptions}>
        <PayPalButtons createOrder={createOrder} />
      </PayPalScriptProvider>
    </div>
  );
}

import {
  PayPalButtons,
  PayPalButtonsComponentProps,
  PayPalScriptProvider,
  ReactPayPalScriptOptions,
} from "@paypal/react-paypal-js";

interface OrderData {
  id: string;
  details?: Array<{ issue: string; description: string }>;
  debug_id?: string;
}

export default function App() {
  const initialOptions: ReactPayPalScriptOptions = {
    clientId: "YOUR_CLIENT_ID",
  };

  const createOrder: PayPalButtonsComponentProps["createOrder"] = async () => {
    try {
      const response = await fetch("/my-server/create-paypal-order", {
        method: "POST",
        headers: { "Content-Type": "application/json" },
        body: JSON.stringify({
          cart: [{ id: "YOUR_PRODUCT_ID", quantity: "YOUR_PRODUCT_QUANTITY" }],
        }),
      });

      const orderData: OrderData = await response.json();

      if (!orderData.id) {
        const errorDetail = orderData?.details?.[0];
        const errorMessage = errorDetail
          ? `${errorDetail.issue} ${errorDetail.description} (${orderData.debug_id})`
          : "Se produjo un error inesperado, por favor inténtelo de nuevo.";

        throw new Error(errorMessage);
      }

      return orderData.id;
    } catch (error) {
      console.error(error);
      throw error;
    }
  };

  return (
    <div className="App">
      <PayPalScriptProvider options={initialOptions}>
        <PayPalButtons createOrder={createOrder} />
      </PayPalScriptProvider>
    </div>
  );
}

import { loadScript } from "@paypal/paypal-js";

let paypal;

try {
  paypal = await loadScript({ clientId: "YOUR_CLIENT_ID" });
} catch (error) {
  console.error("failed to load the PayPal JS SDK script", error);
}

if (paypal) {
  try {
    await paypal.Buttons({
      async createOrder() {
        try {
          const response = await fetch("/my-server/create-paypal-order", {
            method: "POST",
            headers: { "Content-Type": "application/json" },
            body: JSON.stringify({
              cart: [{ id: "YOUR_PRODUCT_ID", quantity: "YOUR_PRODUCT_QUANTITY" }],
            }),
          });

          const orderData = await response.json();

          if (!orderData.id) {
            const errorDetail = orderData.details[0];
            const errorMessage = errorDetail
              ? `${errorDetail.issue} ${errorDetail.description} (${orderData.debug_id})`
              : "Se produjo un error inesperado, por favor inténtelo de nuevo.";

            throw new Error(errorMessage);
          }

          return orderData.id;
        } catch (error) {
          console.error(error);
          throw error;
        }
      }
    }).render("#paypal-button-container");
  } catch (error) {
    console.error("failed to render the PayPal Buttons", error);
  }
}

Servidor (Node.js)

app.post("/my-server/create-paypal-order", async (req, res) => {
  const order = await createOrder();
  res.json(order);
});

// use la API de órdenes para crear una orden
function createOrder() {
  // cree accessToken usando su clientID y clientSecret
  // para el ejemplo completo, por favor vea la guía de Integración Estándar
  // https://developer.paypal.com/docs/multiparty/checkout/standard/integrate/
  const accessToken = "REPLACE_WITH_YOUR_ACCESS_TOKEN";
  return fetch ("https://api-m.sandbox.paypal.com/v2/checkout/orders", {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      Authorization: `Bearer ${accessToken}`,
    }
    body: JSON.stringify({
      "purchase_units": [
        {
          "amount": {
            "currency_code": "USD",
            "value": "100.00"
          },
          "reference_id": "d9f80740-38f0-11e8-b467-0ed5f89f718b"
        }
      ],
      "intent": "CAPTURE",
      "payment_source": {
        "paypal": {
          "experience_context": {
            "payment_method_preference": "IMMEDIATE_PAYMENT_REQUIRED",
            "payment_method_selected": "PAYPAL",
            "brand_name": "EXAMPLE INC",
            "locale": "en-US",
            "landing_page": "LOGIN",
            "shipping_preference": "GET_FROM_FILE",
            "user_action": "PAY_NOW",
            "return_url": "https://example.com/returnUrl",
            "cancel_url": "https://example.com/cancelUrl"
          }
        }
      }
    })
  })
  .then((response) => response.json());
}

Orders v2 API options

intent: La intención de capturar el pago inmediatamente o autorizar un pago para un pedido después de su creación. Los valores son:
- CAPTURE: Predeterminado. El comerciante tiene la intención de capturar el pago inmediatamente después de que el cliente realice el pago.
- AUTHORIZE: El comerciante tiene la intención de autorizar un pago y retener fondos después de que el cliente realice el pago. Los pagos autorizados están garantizados hasta 3 días pero están disponibles para capturar hasta 29 días. Después del período de honor de 3 días, el pago autorizado original expira y necesita volver a autorizar el pago. Necesita hacer una solicitud separada para capturar pagos bajo demanda. Esta intención no es compatible cuando tiene más de 1 purchase_unit dentro de su pedido.
  Consulte autorizar un pago y capturar fondos más tarde.
purchase_units: Requerido. Un array de unidades de compra. Cada unidad de compra establece un contrato entre un pagador y un beneficiario. Cada unidad de compra representa un pedido completo o parcial que el pagador tiene la intención de comprar al beneficiario. Consulte la definición del objeto de solicitud de unidad de compra para obtener información adicional.
payment_source: Opcionalmente defina el payment_source al crear el pedido. Esta fuente de pago puede ser paypal, un token de bóveda, información de card para comerciantes compatibles con PCI, o métodos de pago alternativos como blik y apple_pay. Para más información, consulte API de Pedidos v2 y payment_source.

createSubscription

Proporciona una experiencia de suscripción simplificada y segura. PayPal presenta automáticamente los tipos de pago a sus compradores, facilitándoles completar su compra utilizando métodos como Pago con Venmo, PayPal Credit y pagos con tarjeta de crédito sin reintegración a medida que estén disponibles.

Pase vault=true e intent=subscription en el SDK de JavaScript para configurar una suscripción, en lugar de una transacción única.

<script src="https://www.paypal.com/sdk/js?client-id=YOUR_CLIENT_ID&components=buttons&vault=true&intent=subscription"></script>

import { PayPalScriptProvider, PayPalButtons } from "@paypal/react-paypal-js";

export default function App() {
  const initialOptions = {
    clientId: "YOUR_CLIENT_ID",
    vault: true,
    intent: "subscription",
  };

  return (
    <div className="App">
      <PayPalScriptProvider options={initialOptions}>
        <PayPalButtons />
      </PayPalScriptProvider>
    </div>
  );
}

import { PayPalButtons, PayPalScriptProvider, ReactPayPalScriptOptions } from '@paypal/react-paypal-js';

export default function App() {
  const initialOptions: ReactPayPalScriptOptions = {
    clientId: "YOUR_CLIENT_ID",
    vault: true,
    intent: "subscription",
  };

  return (
    <div className="App">
      <PayPalScriptProvider options={initialOptions}>
        <PayPalButtons />
      </PayPalScriptProvider>
    </div>
  );
}

import { loadScript } from "@paypal/paypal-js";

let paypal;

try {
  paypal = await loadScript({
    clientId: "YOUR_CLIENT_ID",
    vault: true,
    intent: "subscription"
  });
} catch (error) {
  console.error("failed to load the PayPal JS SDK script", error);
}

if (paypal) {
  try {
    await paypal.Buttons().render("#paypal-button-container");
  } catch (error) {
    console.error("failed to render the PayPal Buttons", error);
  }
}

Finalmente, implemente la función createSubscription que se llama cuando el comprador selecciona el botón de PayPal.

Acciones

create — Crea una suscripción para su plan e incluye el ID del plan, detalles del suscriptor, envío y otros detalles. El plan_id debe pertenecer al client-id configurado en el script. Opciones de actions.subscription.create: Consulte el endpoint crear suscripción para ver las opciones soportadas definidas en el cuerpo de la solicitud. También consulte crear un botón de pago para la suscripción para más ejemplos.

paypal.Buttons({
  createSubscription(data, actions) {
    return actions.subscription.create({
      "plan_id": "YOUR_PLAN_ID"
    });
  },
  onApprove(data) {
    alert(`Has creado con éxito la suscripción ${data.subscriptionID}`);
  }
}).render("#paypal-button-container");

import { PayPalButtons, PayPalScriptProvider } from "@paypal/react-paypal-js";

export default function App() {
  const initialOptions = {
    clientId: "YOUR_CLIENT_ID",
    vault: true,
    intent: "subscription"
  };

  const createSubscription = (data, actions) => {
    return actions.subscription.create({
      "plan_id": "YOUR_PLAN_ID"
    });
  };

  const onApprove = (data) => {
    alert(`Te has suscrito con éxito a ${data.subscriptionID}`);
  };

  return (
    <div className="App">
      <PayPalScriptProvider options={initialOptions}>
        <PayPalButtons createSubscription={createSubscription} onApprove={onApprove} />
      </PayPalScriptProvider>
    </div>
  );
}

import { PayPalButtons, PayPalButtonsComponentProps, PayPalScriptProvider, ReactPayPalScriptOptions } from "@paypal/react-paypal-js";

export default function App() {
  const initialOptions: ReactPayPalScriptOptions = {
    clientId: "YOUR_CLIENT_ID",
    vault: true,
    intent: "subscription"
  };

  const createSubscription: PayPalButtonsComponentProps["createSubscription"] = (data, actions) => {
    return actions.subscription.create({
      "plan_id": "YOUR_PLAN_ID"
    });
  };

  const onApprove: PayPalButtonsComponentProps["onApprove"] = async (data) => {
    alert(`Te has suscrito con éxito a ${data.subscriptionID}`);
  };

  return (
    <div className="App">
      <PayPalScriptProvider options={initialOptions}>
        <PayPalButtons createSubscription={createSubscription} onApprove={onApprove} />
      </PayPalScriptProvider>
    </div>
  );
}

import { loadScript } from "@paypal/paypal-js";

let paypal;

try {
  paypal = await loadScript({
    clientId: "YOUR_CLIENT_ID",
    vault: true,
    intent: "subscription"
  });
} catch (error) {
  console.error("failed to load the PayPal JS SDK script", error);
}

if (paypal) {
  try {
    await paypal.Buttons({
      createSubscription(data, actions) {
        return actions.subscription.create({
          "plan_id": "YOUR_PLAN_ID"
        });
      },
      onApprove(data) {
        alert(`Te has suscrito con éxito a ${data.subscriptionID}`);
      }
    }).render("#paypal-button-container");
  } catch (error) {
    console.error("failed to render the PayPal Buttons", error);
  }
}

revise: Actualiza la suscripción que podría estar en estado ACTIVE o SUSPENDED. Consulte actualizar o degradar una suscripción para hacer una revisión utilizando la API de Suscripciones.

onApprove

Captura los fondos de la transacción y muestra un mensaje que indica al comprador que el pago se realizó con éxito. El método se llama después de que el comprador aprueba la transacción en el sitio web paypal.com.

paypal.Buttons({
  async createOrder() {
    const response = await fetch("/my-server/create-paypal-order", {
      method: "POST",
      headers: {
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        cart: [
          {
            sku: "YOUR_PRODUCT_STOCK_KEEPING_UNIT",
            quantity: "YOUR_PRODUCT_QUANTITY",
          },
        ],
      }),
    });

    const data = await response.json();
    return data.id;
  },
  async onApprove(data) {
    const response = await fetch("/my-server/capture-paypal-order", {
      method: "POST",
      body: JSON.stringify({
        orderID: data.orderID
      })
    });

    const details = await response.json();
    alert(`Transacción completada por ${details.payer.name.given_name}`);
  }
}).render('#paypal-button-container');

import { PayPalButtons, PayPalScriptProvider } from "@paypal/react-paypal-js";

export default function App() {
  const initialOptions = {
    clientId: "MY_CLIENT_ID",
  };

  const createOrder = async () => {
    const response = await fetch("/my-server/create-paypal-order", {
      method: "POST",
      headers: {
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        cart: [
          {
            sku: "YOUR_PRODUCT_STOCK_KEEPING_UNIT",
            quantity: "YOUR_PRODUCT_QUANTITY",
          },
        ]
      })
    });

    const data = await response.json();
    return data.id;
  };

  const onApprove = async (data) => {
    const response = await fetch("/my-server/capture-paypal-order", {
      method: "POST",
      body: JSON.stringify({
        orderID: data.orderID
      })
    });

    const details = await response.json();
    alert(`Transacción completada por ${details.payer.name.given_name}`);
  };

  return (
    <div className="App">
      <PayPalScriptProvider options={initialOptions}>
        <PayPalButtons createOrder={createOrder} onApprove={onApprove} />
      </PayPalScriptProvider>
    </div>
  );
}

import {
  PayPalButtons,
  PayPalButtonsComponentProps,
  PayPalScriptProvider,
  ReactPayPalScriptOptions,
} from "@paypal/react-paypal-js";

export default function App() {
  const initialOptions: ReactPayPalScriptOptions = {
    clientId: "YOUR_CLIENT_ID",
  };

  const createOrder: PayPalButtonsComponentProps["createOrder"] = async () => {
    const response = await fetch("/my-server/create-paypal-order", {
      method: "POST",
      headers: {
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        cart: [
          {
            sku: "YOUR_PRODUCT_STOCK_KEEPING_UNIT",
            quantity: "YOUR_PRODUCT_QUANTITY",
          },
        ],
      }),
    });

    const data = await response.json();
    return data.id;
  };

  const onApprove: PayPalButtonsComponentProps["onApprove"] = async (data) => {
    const response = await fetch("/my-server/capture-paypal-order", {
      method: "POST",
      body: JSON.stringify({
        orderID: data.orderID,
      }),
    });

    const details = await response.json();
    alert(`Transacción completada por ${details.payer.name.given_name}`);
  };

  return (
    <div className="App">
      <PayPalScriptProvider options={initialOptions}>
        <PayPalButtons createOrder={createOrder} onApprove={onApprove} />
      </PayPalScriptProvider>
    </div>
  );
}

import { loadScript } from "@paypal/paypal-js";

let paypal;

try {
  paypal = await loadScript({
    clientId: "YOUR_CLIENT_ID",
  });
} catch (error) {
  console.error("failed to load the PayPal JS SDK script", error);
}

if (paypal) {
  try {
    await paypal.Buttons({
      async createOrder() {
        const response = await fetch("/my-server/create-paypal-order", {
          method: "POST",
          headers: {
            "Content-Type": "application/json",
          },
          body: JSON.stringify({
            cart: [
              {
                sku: "YOUR_PRODUCT_STOCK_KEEPING_UNIT",
                quantity: "YOUR_PRODUCT_QUANTITY",
              },
            ],
          }),
        });

        const data = await response.json();
        return data.id;
      },
      async onApprove(data) {
        const response = await fetch("/my-server/capture-paypal-order", {
          method: "POST",
          body: JSON.stringify({
            orderID: data.orderID,
          }),
        });

        const details = await response.json();
        alert(`Transacción completada por ${details.payer.name.given_name}`);
      },
    }).render("#paypal-button-container");
  } catch (error) {
    console.error("failed to render the PayPal Buttons", error);
  }
}

Para la lista de detalles del pedido que recibe de /my-server/capture-paypal-order, consulte capturar pago para pedido en la referencia de la API de Pedidos.

onCancel

Cuando un comprador cancela un pago, normalmente regresa a la página principal. En su lugar, puede usar la función onCancel para mostrar una página de cancelación o regresar al carrito de compras.

Atributos de datos

orderId: El ID del pedido.

paypal.Buttons({
  onCancel(data) {
    window.location.assign("/your-cancel-page");
  }
}).render('#paypal-button-container');

import { PayPalButtons, PayPalScriptProvider } from "@paypal/react-paypal-js";

export default function App() {
  const initialOptions = {
    clientId: "MY_CLIENT_ID",
  };

  const onCancel = (data) => {
    window.location.assign("/your-cancel-page");
  };

  return (
    <div className="App">
      <PayPalScriptProvider options={initialOptions}>
        <PayPalButtons onCancel={onCancel} />
      </PayPalScriptProvider>
    </div>
  );
}

import {
  PayPalButtons,
  PayPalButtonsComponentProps,
  PayPalScriptProvider,
  ReactPayPalScriptOptions,
} from "@paypal/react-paypal-js";

export default function App() {
  const initialOptions: ReactPayPalScriptOptions = {
    clientId: "YOUR_CLIENT_ID",
  };

  const onCancel: PayPalButtonsComponentProps["onCancel"] = (data) => {
    window.location.assign("/your-cancel-page");
  };

  return (
    <div className="App">
      <PayPalScriptProvider options={initialOptions}>
        <PayPalButtons onCancel={onCancel} />
      </PayPalScriptProvider>
    </div>
  );
}

import { loadScript } from "@paypal/paypal-js";

let paypal;

try {
  paypal = await loadScript({
    clientId: "YOUR_CLIENT_ID",
  });
} catch (error) {
  console.error("failed to load the PayPal JS SDK script", error);
}

if (paypal) {
  try {
    await paypal.Buttons({
      onCancel(data) {
        window.location.assign("/your-cancel-page");
      }
    }).render("#paypal-button-container");
  } catch (error) {
    console.error("failed to render the PayPal Buttons", error);
  }
}

onError

Si un error impide el pago del comprador, alerte al usuario que ha ocurrido un error con los botones usando el callback onError:

paypal.Buttons({
  onError(err) {
    window.location.assign("/your-error-page-here");
  }
}).render('#paypal-button-container');

import { PayPalButtons, PayPalScriptProvider } from "@paypal/react-paypal-js";

export default function App() {
  const initialOptions = {
    clientId: "MY_CLIENT_ID",
  };

  const onError = (err) => {
    window.location.assign("/your-error-page-here");
  };

  return (
    <div className="App">
      <PayPalScriptProvider options={initialOptions}>
        <PayPalButtons onError={onError} />
      </PayPalScriptProvider>
    </div>
  );
}

import {
  PayPalButtons,
  PayPalButtonsComponentProps,
  PayPalScriptProvider,
  ReactPayPalScriptOptions,
} from "@paypal/react-paypal-js";

export default function App() {
  const initialOptions: ReactPayPalScriptOptions = {
    clientId: "YOUR_CLIENT_ID",
  };

  const onError: PayPalButtonsComponentProps["onError"] = (err) => {
    window.location.assign("/your-error-page-here");
  };

  return (
    <div className="App">
      <PayPalScriptProvider options={initialOptions}>
        <PayPalButtons onError={onError} />
      </PayPalScriptProvider>
    </div>
  );
}

import { loadScript } from "@paypal/paypal-js";

let paypal;

try {
  paypal = await loadScript({
    clientId: "YOUR_CLIENT_ID",
  });
} catch (error) {
  console.error("failed to load the PayPal JS SDK script", error);
}

if (paypal) {
  try {
    await paypal.Buttons({
      onError(error) {
        window.location.assign("/your-error-page-here");
      }
    }).render("#paypal-button-container");
  } catch (error) {
    console.error("failed to render the PayPal Buttons", error);
  }
}

Nota: Este manejador de errores es general. No se espera que los errores en este punto se manejen más allá de mostrar un mensaje o página de error genérico.

onInit / onClick

Se llama cuando el botón se renderiza por primera vez. Puede usarlo para validaciones en su página si no puede hacerlo antes de renderizar. Por ejemplo, habilitar botones cuando pase la validación del formulario o deshabilitar si falla.

Atributos de datos

fundingSource: La fuente de financiación del botón que se seleccionó. Consulte las fuentes de financiación en la guía de botones independientes.

<!DOCTYPE html>
<html>
  <head>
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
  </head>
  <body>
    <p id="error" class="hidden">Haz clic en la casilla</p>
    <label><input id="check" type="checkbox" required /> Haz clic aquí para continuar</label>
    <div id="paypal-button-container"></div>

    <script src="https://www.paypal.com/sdk/js?client-id=YOUR_CLIENT_ID&components=buttons"></script>

    <script>
      paypal.Buttons({
        onInit(data, actions) {
          actions.disable();

          document.querySelector("#check").addEventListener("change", function (event) {
            if (event.target.checked) {
              actions.enable();
            } else {
              actions.disable();
            }
          });
        },
        onClick() {
          if (!document.querySelector("#check").checked) {
            document.querySelector("#error").classList.remove("hidden");
          }
        },
      }).render("#paypal-button-container");
    </script>
  </body>
</html>

import { useState } from "react";
import { PayPalButtons, PayPalScriptProvider } from "@paypal/react-paypal-js";

export default function App() {
  const [showError, setShowError] = useState(false);
  const [isCheckboxChecked, setIsCheckboxChecked] = useState(false);

  const checkboxChangeHandler = () => {
    setIsCheckboxChecked(!isCheckboxChecked);
  };

  const initialOptions = {
    clientId: "YOUR_CLIENT_ID",
  };

  const onInit = (data, actions) => {
    // En react-paypal-js, use la prop disabled en lugar de actions.disable()
  };

  const onClick = () => {
    if (!isCheckboxChecked) setShowError(true);
  };

  return (
    <div className="App">
      {showError && <p>Haz clic en la casilla</p>}
      <label><input type="checkbox" onChange={checkboxChangeHandler} /> Haz clic aquí para continuar</label>

      <PayPalScriptProvider options={initialOptions}>
        <PayPalButtons onInit={onInit} onClick={onClick} disabled={!isCheckboxChecked} />
      </PayPalScriptProvider>
    </div>
  );
}

import { useState } from "react";
import {
  PayPalButtons,
  PayPalButtonsComponentProps,
  PayPalScriptProvider,
  ReactPayPalScriptOptions,
} from "@paypal/react-paypal-js";

export default function App() {
  const [showError, setShowError] = useState(false);
  const [isCheckboxChecked, setIsCheckboxChecked] = useState(false);

  const checkboxChangeHandler = () => {
    setIsCheckboxChecked(!isCheckboxChecked);
  };

  const initialOptions: ReactPayPalScriptOptions = {
    clientId: "YOUR_CLIENT_ID",
  };

  const onInit: PayPalButtonsComponentProps["onInit"] = (data, actions) => {
    // Con react-paypal-js, use la prop disabled en lugar de actions.disable()
  };

  const onClick: PayPalButtonsComponentProps["onClick"] = () => {
    if (!isCheckboxChecked) setShowError(true);
  };

  return (
    <div className="App">
      {showError && <p>Haz clic en la casilla</p>}
      <label><input type="checkbox" onChange={checkboxChangeHandler} /> Haz clic aquí para continuar</label>

      <PayPalScriptProvider options={initialOptions}>
        <PayPalButtons onInit={onInit} onClick={onClick} disabled={!isCheckboxChecked} />
      </PayPalScriptProvider>
    </div>
  );
}

import { loadScript } from "@paypal/paypal-js";

let paypal;
const checkbox = document.querySelector("#check");
const errorMessage = document.querySelector("#error");

try {
  paypal = await loadScript({ clientId: "YOUR_CLIENT_ID" });
} catch (error) {
  console.error("failed to load the PayPal JS SDK script", error);
}

if (paypal) {
  try {
    await paypal.Buttons({
      onInit(data, actions) {
        actions.disable();

        checkbox.addEventListener("change", function (event) {
          if (event.target.checked) {
            actions.enable();
          } else {
            actions.disable();
          }
        });
      },
      onClick() {
        if (!checkbox.checked) {
          errorMessage.classList.remove("hidden");
        }
      },
    }).render("#paypal-button-container");
  } catch (error) {
    console.error("failed to render the PayPal Buttons", error);
  }
}

Para casos cuando necesita validación asíncrona, consulte validación asíncrona.

paypal.Buttons().isEligible()

Comúnmente usado para botones independientes cuando necesita verificar si la fuente de financiación es elegible.

paypal.getFundingSources().forEach(function(fundingSource) {
  const button = paypal.Buttons({
    fundingSource: fundingSource
  });

  if (button.isEligible()) {
    button.render('#paypal-button-container');
  }
});

import { loadScript } from "@paypal/paypal-js";

let paypal;

try {
  paypal = await loadScript({
    clientId: "YOUR_CLIENT_ID",
  });
} catch (error) {
  console.error("failed to load the PayPal JS SDK script", error);
}

if (paypal) {
  try {
    paypal.getFundingSources().forEach(function(fundingSource) {
      const button = paypal.Buttons({
        fundingSource: fundingSource
      });

      if (button.isEligible()) {
        button.render('#paypal-button-container');
      }
    });
  } catch (error) {
    console.error("failed to render the PayPal Buttons", error);
  }
}

paypal.Buttons().render(container)

Renderiza los botones en el selector de contenedor definido.

paypal.Buttons().render("#paypal-buttons-container");

import { loadScript } from "@paypal/paypal-js";

let paypal;

try {
  paypal = await loadScript({
    clientId: "YOUR_CLIENT_ID",
  });
} catch (error) {
  console.error("failed to load the PayPal JS SDK script", error);
}

if (paypal) {
  try {
    await paypal.Buttons().render("#paypal-button-container");
  } catch (error) {
    console.error("failed to render the PayPal Buttons", error);
  }
}

onShippingChange

Obsoleto: Consulte onShippingAddressChange y onShippingOptionsChange

Mientras el comprador está en el sitio de PayPal, puede actualizar su carrito de compras para reflejar la dirección de envío que seleccionó en PayPal. Puede usar el callback para:

Validar que admite la dirección de envío.
Actualizar los costos de envío.
Cambiar los artículos en el carrito.
Informar al comprador que no admite su dirección de envío.

Disponibilidad: La función onShippingChange no es compatible con Suscripciones.

Atributos de datos

data: Un objeto que contiene la dirección de envío del comprador. Consiste en los siguientes campos:

orderID (requerido): Un ID que representa un pedido.
paymentID (opcional): Un ID que representa un pago.
paymentToken (requerido): Un ID o token que representa el recurso.
shipping_address (requerido): La ciudad, estado, país y código postal seleccionados por el comprador.
- city: Ciudad de la dirección de envío.
- state: Estado o provincia de la dirección de envío.
- country_code: País de la dirección de envío.
- postal_code: Código postal o código postal de la dirección de envío.
selected_shipping_option (opcional): Opción de envío seleccionada por el comprador.
- label: Etiqueta personalizada del método de envío.
- type: Tipo de método de envío (SHIPPING o PICKUP).
- amount: Costo adicional para este método.
  - currency_code: Código de moneda ISO, como USD.
  - value: Formato decimal en cadena, como 1.00.

Acciones

actions: Un objeto que contiene métodos para actualizar el contenido del carrito del comprador e interactuar con PayPal Checkout. Consiste en los siguientes métodos:

resolve: Indica a PayPal que no necesita hacer ningún cambio en el carrito del comprador.
reject: Indica a PayPal que no admitirá la dirección de envío proporcionada por el comprador.
order: Método de API de pedido del lado del cliente.
- PATCH: Para hacer la actualización, pase un array de operaciones de cambio en la solicitud, como se describe en la referencia de la API de actualización de pedido. La respuesta devuelve una promesa.

Ejemplos

Este ejemplo muestra no admitir transacciones internacionales:

paypal.Buttons({
  onShippingChange(data, actions) {
    if (data.shipping_address.country_code !== 'US') {
      return actions.reject();
    }
    return actions.resolve();
  }
}).render('#paypal-button-container');

import { PayPalButtons, PayPalScriptProvider } from "@paypal/react-paypal-js";

export default function App() {
  const initialOptions = { clientId: "YOUR_CLIENT_ID" };

  const onShippingChange = (data, actions) => {
    if (data.shipping_address.country_code !== "US") {
      return actions.reject();
    }
    return actions.resolve();
  };

  return (
    <div className="App">
      <PayPalScriptProvider options={initialOptions}>
        <PayPalButtons onShippingChange={onShippingChange} />
      </PayPalScriptProvider>
    </div>
  );
}

import {
  PayPalButtons,
  PayPalButtonsComponentProps,
  PayPalScriptProvider,
  ReactPayPalScriptOptions,
} from "@paypal/react-paypal-js";

export default function App() {
  const initialOptions: ReactPayPalScriptOptions = { clientId: "YOUR_CLIENT_ID" };

  const onShippingChange: PayPalButtonsComponentProps["onShippingChange"] = (data, actions) => {
    if (data.shipping_address?.country_code !== "US") {
      return actions.reject();
    }
    return actions.resolve();
  };

  return (
    <div className="App">
      <PayPalScriptProvider options={initialOptions}>
        <PayPalButtons onShippingChange={onShippingChange} />
      </PayPalScriptProvider>
    </div>
  );
}

import { loadScript } from "@paypal/paypal-js";

let paypal;

try {
  paypal = await loadScript({ clientId: "YOUR_CLIENT_ID" });
} catch (error) {
  console.error("failed to load the PayPal JS SDK script", error);
}

if (paypal) {
  try {
    await paypal.Buttons({
      onShippingChange(data, actions) {
        if (data.shipping_address.country_code !== "US") {
          return actions.reject();
        }
        return actions.resolve();
      }
    }).render("#paypal-button-container");
  } catch (error) {
    console.error("failed to render the PayPal Buttons", error);
  }
}

Este ejemplo muestra una situación más compleja en la que un estado tiene envío gratuito, pero el envío de tarifa fija es el estándar para el resto de los EE. UU.:

paypal.Buttons({
  async onShippingChange(data, actions) {
    if (data.shipping_address.country_code !== 'US') {
      return actions.reject();
    }

    await fetch("/my-server/patch-paypal-order", {
      method: "PATCH",
      body: JSON.stringify({
        shippingAddress: data.shipping_address
      })
    });

    return actions.resolve();
  }
}).render('#paypal-button-container');

import { PayPalButtons, PayPalScriptProvider } from "@paypal/react-paypal-js";

export default function App() {
  const initialOptions = { clientId: "YOUR_CLIENT_ID" };

  const onShippingChange = async (data, actions) => {
    if (data.shipping_address.country_code !== 'US') {
      return actions.reject();
    }

    await fetch("/my-server/patch-paypal-order", {
      method: "PATCH",
      body: JSON.stringify({
        shippingAddress: data.shipping_address
      })
    });

    return actions.resolve();
  };

  return (
    <div className="App">
      <PayPalScriptProvider options={initialOptions}>
        <PayPalButtons onShippingChange={onShippingChange} />
      </PayPalScriptProvider>
    </div>
  );
}

import {
  PayPalButtons,
  PayPalButtonsComponentProps,
  PayPalScriptProvider,
  ReactPayPalScriptOptions,
} from "@paypal/react-paypal-js";

export default function App() {
  const initialOptions: ReactPayPalScriptOptions = { clientId: "YOUR_CLIENT_ID" };

  const onShippingChange: PayPalButtonsComponentProps["onShippingChange"] = async (data, actions) => {
    if (data.shipping_address?.country_code !== 'US') {
      return actions.reject();
    }

    await fetch("/my-server/patch-paypal-order", {
      method: "PATCH",
      body: JSON.stringify({
        shippingAddress: data.shipping_address
      })
    });

    return actions.resolve();
  };

  return (
    <div className="App">
      <PayPalScriptProvider options={initialOptions}>
        <PayPalButtons onShippingChange={onShippingChange} />
      </PayPalScriptProvider>
    </div>
  );
}

import { loadScript } from "@paypal/paypal-js";

let paypal;

try {
  paypal = await loadScript({ clientId: "YOUR_CLIENT_ID" });
} catch (error) {
  console.error("failed to load the PayPal JS SDK script", error);
}

if (paypal) {
  try {
    await paypal.Buttons({
      async onShippingChange(data, actions) {
        if (data.shipping_address.country_code !== 'US') {
          return actions.reject();
        }

        await fetch("/my-server/patch-paypal-order", {
          method: "PATCH",
          body: JSON.stringify({
            shippingAddress: data.shipping_address
          })
        });

        return actions.resolve();
      }
    }).render("#paypal-button-container");
  } catch (error) {
    console.error("failed to render the PayPal Buttons", error);
  }
}

onShippingAddressChange

Mientras el comprador está en el sitio de PayPal, puedes actualizar su carrito de compras para reflejar la dirección de envío que seleccionó en PayPal. Puedes usar la función de devolución para:

Validar que admites la dirección de envío.
Actualizar los costos de envío.
Cambiar los artículos en el carrito.
Informar al comprador que no admites su dirección de envío.

Disponibilidad: La función onShippingAddressChange no es compatible con Suscripciones.

Atributos de datos

data: Un objeto que contiene la dirección de envío del comprador. Consiste en las siguientes propiedades:

errors: Errores para mostrar al usuario.
- ADDRESS_ERROR: "Tu pedido no puede ser enviado a esta dirección."
- COUNTRY_ERROR: "Tu pedido no puede ser enviado a este país."
- STATE_ERROR: "Tu pedido no puede ser enviado a este estado."
- ZIP_ERROR: "Tu pedido no puede ser enviado a este código postal."
orderID: Un ID que representa un pedido.
paymentID: Un ID que representa un pago.
paymentToken: Un ID o token que representa un recurso.
shippingAddress: La ciudad, estado, país y código postal seleccionados por el comprador.
- city: Ciudad de la dirección de envío.
- countryCode: País de la dirección de envío.
- postalCode: Código postal o código postal de la dirección de envío.
- state: Estado o provincia de la dirección de envío.

Acciones

actions: Un objeto que contiene un método para interactuar con PayPal Checkout. Consiste en la siguiente propiedad:

reject: Indica a PayPal que no admitirás la dirección de envío proporcionada por el comprador.

Ejemplos

Este ejemplo muestra cómo rechazar transacciones internacionales usando actions.reject():

paypal.Buttons({
  onShippingAddressChange(data, actions) {
    if (data.shippingAddress.countryCode !== "US") {
      return actions.reject(data.errors.COUNTRY_ERROR);
    }
  }
}).render('#paypal-button-container');

import { PayPalButtons, PayPalScriptProvider } from "@paypal/react-paypal-js";

export default function App() {
  const initialOptions = { clientId: "YOUR_CLIENT_ID" };

  const onShippingAddressChange = (data, actions) => {
    if (data.shippingAddress.countryCode !== "US") {
      return actions.reject(data.errors.COUNTRY_ERROR);
    }
  };

  return (
    <div className="App">
      <PayPalScriptProvider options={initialOptions}>
        <PayPalButtons onShippingAddressChange={onShippingAddressChange} />
      </PayPalScriptProvider>
    </div>
  );
}

import {
  PayPalButtons,
  PayPalButtonsComponentProps,
  PayPalScriptProvider,
  ReactPayPalScriptOptions,
} from "@paypal/react-paypal-js";

export default function App() {
  const initialOptions: ReactPayPalScriptOptions = { clientId: "YOUR_CLIENT_ID" };

  const onShippingAddressChange: PayPalButtonsComponentProps["onShippingAddressChange"] = (data, actions) => {
    if (data.shippingAddress.countryCode !== "US") {
      return actions.reject(data.errors?.COUNTRY_ERROR);
    }
  };

  return (
    <div className="App">
      <PayPalScriptProvider options={initialOptions}>
        <PayPalButtons onShippingAddressChange={onShippingAddressChange} />
      </PayPalScriptProvider>
    </div>
  );
}

import { loadScript } from "@paypal/paypal-js";

let paypal;

try {
  paypal = await loadScript({ clientId: "YOUR_CLIENT_ID" });
} catch (error) {
  console.error("failed to load the PayPal JS SDK script", error);
}

if (paypal) {
  try {
    await paypal.Buttons({
      onShippingAddressChange(data, actions) {
        if (data.shippingAddress.countryCode !== "US") {
          return actions.reject(data.errors.COUNTRY_ERROR);
        }
      }
    }).render("#paypal-button-container");
  } catch (error) {
    console.error("failed to render the PayPal Buttons", error);
  }
}

onShippingOptionsChange

Esta función de devolución se activa cada vez que el usuario selecciona una nueva opción de envío. Puedes usar la función de devolución para:

Validar que admites el método de envío.
Actualizar los costos de envío.
Cambiar los artículos en el carrito.
Informar al comprador que no admites su método de envío.

Disponibilidad: La función onShippingOptionsChange no es compatible con Suscripciones.

Atributos de datos

data: Un objeto que contiene la opción de envío seleccionada por el pagador. Consiste en las siguientes propiedades:

errors: Errores para mostrar al pagador.
- METHOD_UNAVAILABLE: "El método de envío que seleccionaste no está disponible. Para continuar, elige otra forma de recibir tu pedido."
- STORE_UNAVAILABLE: "Parte de tu pedido no está disponible en esta tienda."
orderID: Un ID que representa un pedido.
paymentID: Un ID que representa un pago.
paymentToken: Un ID o token que representa un recurso.
selectedShippingOption: Opción de envío seleccionada por el pagador.
- id: ID personalizado del método de envío.
- label: Etiqueta personalizada del método de envío.
- selected: Establecido como true por PayPal cuando es seleccionado por el comprador.
- type: Tipo de método de envío (SHIPPING o PICKUP).
- amount: Costo adicional para este método.
  - currencyCode: Código de moneda ISO, como USD.
  - value: Formato decimal en cadena, como 1.00.

Acciones

actions: Un objeto que contiene un método para interactuar con PayPal Checkout. Consiste en la siguiente propiedad:

reject: Indica a PayPal que no admitirás el método de envío seleccionado por el comprador.

Personalizar opciones de envío

Añade soporte para múltiples opciones de envío cuando los compradores realizan cambios en su información de envío.

Ejemplos

Este ejemplo muestra cómo deshabilitar la recogida en tienda usando actions.reject():

paypal.Buttons({
  onShippingOptionsChange(data, actions) {
    if (data.selectedShippingOption.type === 'PICKUP') {
      return actions.reject(data.errors.STORE_UNAVAILABLE);
    }
  }
}).render('#paypal-button-container');

import { PayPalButtons, PayPalScriptProvider } from "@paypal/react-paypal-js";

export default function App() {
  const initialOptions = { clientId: "YOUR_CLIENT_ID" };

  const onShippingOptionsChange = (data, actions) => {
    if (data.selectedShippingOption.type === 'PICKUP') {
      return actions.reject(data.errors.STORE_UNAVAILABLE);
    }
  };

  return (
    <div className="App">
      <PayPalScriptProvider options={initialOptions}>
        <PayPalButtons onShippingOptionsChange={onShippingOptionsChange} />
      </PayPalScriptProvider>
    </div>
  );
}

import {
  PayPalButtons,
  PayPalButtonsComponentProps,
  PayPalScriptProvider,
  ReactPayPalScriptOptions,
} from "@paypal/react-paypal-js";

export default function App() {
  const initialOptions: ReactPayPalScriptOptions = { clientId: "YOUR_CLIENT_ID" };

  const onShippingOptionsChange: PayPalButtonsComponentProps["onShippingOptionsChange"] = (data, actions) => {
    if (data.selectedShippingOption.type === 'PICKUP') {
      return actions.reject(data.errors?.STORE_UNAVAILABLE);
    }
  };

  return (
    <div className="App">
      <PayPalScriptProvider options={initialOptions}>
        <PayPalButtons onShippingOptionsChange={onShippingOptionsChange} />
      </PayPalScriptProvider>
    </div>
  );
}

import { loadScript } from "@paypal/paypal-js";

let paypal;

try {
  paypal = await loadScript({ clientId: "YOUR_CLIENT_ID" });
} catch (error) {
  console.error("failed to load the PayPal JS SDK script", error);
}

if (paypal) {
  try {
    await paypal.Buttons({
      onShippingOptionsChange(data, actions) {
        if (data.selectedShippingOption.type === 'PICKUP') {
          return actions.reject(data.errors?.STORE_UNAVAILABLE);
        }
      }
    }).render("#paypal-button-container");
  } catch (error) {
    console.error("failed to render the PayPal Buttons", error);
  }
}

Marcas

Usa marcas cuando los botones de PayPal se presentan junto con otras fuentes de financiación en la página y los botones de PayPal se muestran cuando el comprador selecciona un botón de radio. Consulta Mostrar otros métodos de pago.

<script src="https://www.paypal.com/sdk/js?client-id=YOUR_CLIENT_ID&components=buttons,marks"></script>

`paypal.Marks(options)`

`paypal.Marks().isEligible`

<script src="https://www.paypal.com/sdk/js?client-id=YOUR_CLIENT_ID&components=buttons,funding-eligibility,marks"></script>

Comúnmente usado para botones independientes cuando necesitas verificar si la fuente de financiación es elegible.

// Recorrer cada fuente de financiación / método de pago
paypal.getFundingSources().forEach(function(fundingSource) {

  // Inicializar las marcas
  var mark = paypal.Marks({
    fundingSource: fundingSource
  });

  // Verificar si la marca es elegible
  if (mark.isEligible()) {

    // Renderizar la marca independiente para esa fuente de financiación
    mark.render('#paypal-mark-container');
  }
});

`paypal.Marks().render(container)`

Renderiza los botones de radio que se pasan en el selector de contenedor.

paypal.Marks().render('#paypal-marks-container');

<!-- Renderizar los botones de radio y las marcas -->
<label>
  <input type="radio" name="payment-option" value="paypal" checked>
  <div id="paypal-marks-container"></div>
</label>

<label>
  <input type="radio" name="payment-option" value="alternate">
</label>

<div id="paypal-buttons-container"></div>
<div id="alternate-button-container">
  <button>Pagar con un método diferente</button>
</div>

<script>
  paypal.Marks().render('#paypal-marks-container');
  paypal.Buttons().render('#paypal-buttons-container');

  document.querySelectorAll('input[name=payment-option]').forEach(function (el) {
    el.addEventListener('change', function (event) {
      if (event.target.value === 'paypal') {
        document.body.querySelector('#alternate-button-container').style.display = 'none';
        document.body.querySelector('#paypal-buttons-container').style.display = 'block';
      }
      if (event.target.value === 'alternate') {
        document.body.querySelector('#alternate-button-container').style.display = 'block';
        document.body.querySelector('#paypal-buttons-container').style.display = 'none';
      }
    });
  });

  document.body.querySelector('#alternate-button-container').style.display = 'none';
</script>

Campos de tarjeta

Usa campos de tarjeta alojados por PayPal para aceptar y guardar tarjetas de crédito y débito sin manejar información de tarjetas. PayPal maneja todos los problemas de seguridad y cumplimiento asociados con el procesamiento de tarjetas.

Solicitud: Inicializar cardFields

Inicializa el componente de campos de tarjeta creando una instancia de paypal.CardFields:

const cardFields = paypal.CardFields({
  style,
  createOrder,
  onApprove
});

Opciones

Puedes pasar las siguientes opciones al instanciar el componente de campos de tarjeta:

Opción

Descripción

Requerido

createOrder

La función de devolución para crear el pedido en tu servidor.

Sí

onApprove

La función de devolución para capturar el pedido en tu servidor.

Sí

onError

La función de devolución para capturar errores durante el pago.

Sí

inputEvents

Objeto que contiene funciones de devolución para eventos de entrada.

style

Objeto de estilo personalizado.

createOrder

Crea un ID de pedido para cualquier caso que implique una compra. Esta función de devolución se llama cada vez que el pagador envía los campos de tarjeta.

Solicitud: Crear pedido desde el servidor

const createOrder = (data, actions) => {
  return fetch('/api/paypal/order', { method: 'POST' })
    .then(res => res.json())
    .then(json => json.orderID);
};

Configura tu servidor para llamar a la API de Crear Pedido. El botón presionado en el lado del cliente determina la fuente de pago enviada. En el siguiente ejemplo, el pagador optó por enviar su tarjeta como fuente de pago.

Solicitud: Crear pedido con una tarjeta como fuente de pago

curl -v -X POST https://api-m.sandbox.paypal.com/v2/checkout/orders \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ACCESS-TOKEN" \
  -d '{
    "intent": "CAPTURE",
    "purchase_units": [{
      "amount": { "currency_code": "USD", "value": "100.00" }
    }]
}'

Respuesta

Pasa el order.id al SDK de JavaScript para actualizar el pedido con el número, CVV y fecha de vencimiento ingresados.

{
      "id": "5O190127TN364715T",
      "status": "CREATED",
      "intent": "CAPTURE",
      "purchase_units": [
          {
              "reference_id": "d9f80740-38f0-11e8-b467-0ed5f89f718b",
              "amount": {
                  "currency_code": "USD",
                  "value": "100.00"
              }
          }
      ],
      "create_time": "2022-10-03T11:18:49Z",
      "links": [
          {
              "href": "https://api-m.paypal.com/v2/checkout/orders/5O190127TN364715T",
              "rel": "self",
              "method": "GET"
          },
          {
              "href": "https://www.paypal.com/checkoutnow?token=5O190127TN364715T",
              "rel": "approve",
              "method": "GET"
          },
          {
              "href": "https://api-m.paypal.com/v2/checkout/orders/5O190127TN364715T",
              "rel": "update",
              "method": "PATCH"
          },
          {
              "href": "https://api-m.paypal.com/v2/checkout/orders/5O190127TN364715T/capture",
              "rel": "capture",
              "method": "POST"
          }
      ]
}

onApprove

Señala que un pagador aprobó una compra enviando una tarjeta o seleccionando un botón.

Solicitud: Capturar pedido desde el servidor

Configura tu servidor para llamar a la API de Capturar Pedido, luego ejecuta el siguiente script para capturar un pedido desde tu servidor:

const onApprove = (data, actions) => {
    return fetch('/api/paypal/order/capture', {
        method: 'POST',
        body: JSON.stringify({
            orderID: data.orderID
        })
    }).then(res => {
        return res.json();
    }).then(json => {
        // Show a success page
    });
};

Solicitud

curl -v -X POST https://api-m.sandbox.paypal.com/v2/checkout/orders/<order_id>/capture 
 -H "Content-Type: application/json" 
 -H "Authorization: Bearer ACCESS-TOKEN"

Respuesta

{
  "id": "some_id",
  "status": "COMPLETED",
  "payment_source": {
    "card": {
      "brand": "VISA",
      "last_digits": "1111",
      "type": "CREDIT"
    }
  },
  "purchase_units": [
    {
      "reference_id": "reference_id",
      "payments": {
        "authorizations": [
          {
            "id": "id",
            "status": "CREATED",
            "amount": {
              "currency_code": "USD",
              "value": "100.00"
            },
            "seller_protection": {
              "status": "ELIGIBLE",
              "dispute_categories": [
                "ITEM_NOT_RECEIVED",
                "UNAUTHORIZED_TRANSACTION"
              ]
            },
            "expiration_time": "2022-10-04T14:37:39Z",
            "links": [
              {
                "href": "https://api-m.paypal.com/v2/payments/authorizations/5O190127TN364715T",
                "rel": "self",
                "method": "GET"
              },
              {
                "href": "https://api-m.paypal.com/v2/payments/authorizations/5O190127TN364715T/capture",
                "rel": "capture",
                "method": "POST"
              },
              {
                "href": "https://api-m.paypal.com/v2/payments/authorizations/5O190127TN364715T/void",
                "rel": "void",
                "method": "POST"
              },
              {
                "href": "https://api-m.paypal.com/v2/checkout/orders/5O190127TN364715T",
                "rel": "up",
                "method": "GET"
              }
            ]
          }
        ]
      }
    }
  ],
  "payer": {
    "name": {
      "given_name": "Firstname",
      "surname": "Lastname"
    },
    "email_address": "[email protected]",
    "payer_id": "QYR5Z8XDVJNXQ"
  },
  "links": [
    {
      "href": "https://api-m.paypal.com/v2/checkout/orders/5O190127TN364715T",
      "rel": "self",
      "method": "GET"
    }
  ]
}

onError

Maneja cualquier error que ocurra mientras el pagador envía el formulario.

const cardFields = paypal.CardFields({
    // ...
    onError = (error) => {
        // Handle the error object
        console.error(error);
    },
    // ...
});

onCancel

Para casos de uso de 3D Secure, puedes elegir qué presentar al cliente si cierran el modal de verificación. Esto también significará que la transacción fue cancelada.

const cardFields = paypal.CardFields({
  // ...
  onCancel: () => {
    console.log("Your order was cancelled due to incomplete verification");
  },
  // ...
});

Propiedades de Campos de Tarjeta

Las siguientes propiedades de campo de tarjeta se utilizan para capturar un pago. Usa el método render() para renderizar estas instancias al DOM.

Propiedad

Tipo

Campo creado

Requerido

CVVField

Función

CVV o CID de la tarjeta, un código de 3 o 4 dígitos

Sí

ExpiryField

Función

Fecha de vencimiento de la tarjeta

Sí

NameField

Función

Nombre para la tarjeta

NumberField

Función

Número de tarjeta

Sí

Opciones de campo de tarjeta

Personaliza las funciones de devolución de eventos o el estilo de cada campo con las siguientes opciones:

Opción

Tipo

Descripción

Requerido

inputEvents

Objeto

Un objeto que contiene funciones de devolución para cuando ocurre un evento de entrada específico para un campo.

style

Objeto

Estiliza un campo con propiedades CSS soportadas.

placeholder

String

Cada campo de tarjeta tiene un texto de marcador de posición predeterminado. Pasa un objeto de marcador de posición para personalizar este texto.

Ejemplo: Propiedades de campo de tarjeta

const cardNameContainer = document.getElementById("card-name-field-container");
const nameField = cardField.NameField({
  placeholder: "Ingresa tu nombre completo como aparece en tu tarjeta",
inputEvents: {
    onChange: (event)=> {
        console.log("devuelve un stateObject", event);
    }
},
style: {
    ".invalid": {
        "color": "purple",
    }
}
});
  });
nameField.render(cardNameContainer);
const cardNumberContainer = document.getElementById("card-number-field-container");
const numberField = cardField.NumberField(/*options*/);
numberField.render(cardNumberContainer);
const cardExpiryContainer = document.getElementById("card-expiry-field-container");
const expiryField = cardField.ExpiryField(/*options*/);
expiryField.render(cardExpiryContainer);
const cardCvvContainer = document.getElementById("card-cvv-field-container");
const cvvField = cardField.CVVField(/*options*/);
cvvField.render(cardCvvContainer);

Estilizar campos de tarjeta

Cambia el diseño, ancho, alto y estilo exterior de los campos de tarjeta. Modifica los elementos que proporcionas como contenedores con tus hojas de estilo actuales. Por ejemplo, input: { border: 1px solid #333; }.

Propiedades CSS soportadas

Las propiedades CSS listadas son las únicas propiedades soportadas en la configuración de pagos avanzados con tarjeta de crédito y débito. Si especificas una propiedad CSS no soportada, se registra una advertencia en la consola del navegador.

appearance
color
direction
font
font-family
font-size
font-size-adjust
font-stretch
font-style
font-variant
font-variant-alternates
font-variant-caps
font-variant-east-asian
font-variant-ligatures
font-variant-numeric
font-weight
letter-spacing
line-height
opacity
outline
padding
padding-bottom
padding-left
padding-right
padding-top
text-shadow
transition
-moz-appearance
-moz-osx-font-smoothing
-moz-tap-highlight-color
-moz-transition
-webkit-appearance
-webkit-osx-font-smoothing
-webkit-tap-highlight-color
-webkit-transition

Estilizar campos padre

Pasa un objeto de estilo al componente padre cardField para aplicar el objeto a cada campo.

const cardStyle = {
    'input': {
        'font-size': '16px',
        'font-family': 'courier, monospace',
        'font-weight': 'lighter',
        'color': '#ccc',
    },
    '.invalid': {
        'color': 'purple',
    },
};
const cardField = paypal.CardFields({
    style: cardStyle
});

Estilizar campos individuales

Pasa un objeto style a un campo de tarjeta individual para aplicar el objeto solo a ese campo. Esto anula cualquier objeto pasado a través de un componente padre.


const nameFieldStyle = {
    'input': {
        'color': 'blue'
    }
    '.invalid': {
        'color': 'purple'
    },
};
const nameField = cardField.NameField({
    style: nameFieldStyle
}).render('#card-name-field-container');

inputEvents

Puedes pasar un objeto inputEvents a un componente padre cardField o a cada campo de tarjeta individualmente.

Pasa un objeto inputEvents al componente padre cardField para aplicar el objeto a cada campo.

Pasa un objeto inputEvents a un campo de tarjeta individual para aplicar el objeto solo a ese campo. Esto anula cualquier objeto pasado a través de un componente padre.

Funciones de devolución de eventos de entrada soportadas

Puedes pasar las siguientes funciones de devolución al objeto inputEvents:

Nombre del Evento

Descripción

onChange

Se llama cuando cambia la entrada en cualquier campo.

onFocus

Se llama cuando cualquier campo obtiene el foco.

onBlur

Se llama cuando cualquier campo pierde el foco.

onInputSubmitRequest

Se llama cuando un pagador envía el campo.

Ejemplo: inputEvents en componente padre

Pasa el objeto inputEvents al componente padre CardFields.

const cardField = paypal.CardFields({
    inputEvents: {
        onChange: function(data) => {
            // Hacer algo cuando cambia una entrada
        },
        onFocus: function(data) => {
            // Hacer algo cuando un campo obtiene el foco
        },
        onBlur: function(data) => {
            // Hacer algo cuando un campo pierde el foco
        }
        onInputSubmitRequest: function(data) => {
            if (data.isFormValid) {
                // Enviar el formulario de tarjeta para el pagador
            } else {
                // Informar al pagador que algunos campos no son válidos
            }
        }
    }
})

Ejemplo: inputEvents en componente individual

Pasa el objeto inputEvents a cada componente de campo individual:


const cardField = paypal.CardFields(/* options */)
const nameField = cardField.NameField({
       inputEvents: {
        onChange: function(data) => {
            // Hacer algo cuando cambia la entrada solo del campo de nombre
        },
        onFocus: function(data) => {
            // Hacer algo cuando solo el campo de nombre obtiene el foco
        },
        onBlur: function(data) => {
            // Hacer algo cuando solo el campo de nombre pierde el foco
        }
        onInputSubmitRequest: function(data) => {
            if (data.isFormValid) {
                // Enviar el formulario de tarjeta para el pagador
            } else {
                // Informar al pagador que algunos campos no son válidos
            }
        }
    }
});

objeto-estado-muestra

Cada una de las funciones de devolución de eventos devuelve un objeto de estado similar al siguiente ejemplo:

data: {
    cards: [{code: {name: 'CVV', size: 3}, niceType: "Visa", type: "visa"}]
    emittedBy: "number", // No se devuelve para getState()
    isFormValid: false,
    errors: ["INVALID_CVV"]
    fields: {
        cardCvvField: {
            isFocused: false,
            isEmpty: true,
            isValid: false,
            isPotentiallyValid: true,
        },
        cardNumberField: {
            isFocused: true,
            isEmpty: false,
            isValid: false,
            isPotentiallyValid: true,
        },
        cardNameField: {
            isFocused: false,
            isEmpty: true,
            isValid: false,
            isPotentiallyValid: true,
        },
        cardExpiryField: {
            isFocused: false,
            isEmpty: true,
            isValid: false,
            isPotentiallyValid: true,
        },
    },
}

Validar campos individuales

Valida campos individuales cuando ocurre un evento de entrada:

const cardFields = paypal.CardFields({/* options */});
let cardContainer = document.getElementById("#card-number-field-container")
const cardNumberField = cardFields.NumberField({
    // Añadir clase válida o inválida cuando cambia la validación en el campo
    inputEvents: {
        onChange: (data) => {
            cardContainer.className = data.fields.cardNumberField.isValid ? 'valid' : 'invalid';
        }
    }
})

Validar formulario de tarjeta completo

Valida un formulario de tarjeta completo cuando ocurre un evento de entrada:

const formContainer = document.getElementById("form-container")
const cardFields = paypal.CardFields({
    inputEvents: {
        onChange: (data) => {
            formContainer.className = data.isFormValid ? 'valid' : 'invalid'
        }
    }
});

Métodos en campos de tarjeta padre

Los siguientes métodos son soportados en campos de tarjeta padre:

getState()
isEligible()
submit()

getState() -> {promise | void}

Devuelve una promesa que se resuelve en un stateObject. Incluye el estado de todos los campos, posibles tipos de tarjeta y un array de errores.

Ejemplo

const cardField = paypal.CardFields(/* options */)
// ...
// Renderizar los campos de tarjeta
// ...
cardFields.getState().then((data) => {
    // Enviar solo si el estado actual
    // del formulario es válido
    if (data.isFormValid) {
        cardFields.submit().then(() => {
            //Envío exitoso
        }).catch((error) => {
            //Error de envío
        });
    }
});

isEligible() -> {Boolean}

Verifica si una instancia de cardField puede renderizarse basándose en la configuración y reglas de negocio.

Ejemplo

const cardField = paypal.CardFields(/* options */)
if (cardFields.isEligible()) {
  cardFields.NumberField().render("#card-number-field-container");
  cardFields.CVVField().render("#card-cvv-field-container");
  // ...
}

submit() -> {promise | void}

Envía información de pago.

Ejemplo

// Añadir listener de clic al botón de envío proporcionado por el comerciante
// y llamar a la función submit en el componente CardField
multiCardFieldButton.addEventListener("click", () => {
  cardField.submit().then(() => {
    console.log("Envío de Campos de Tarjeta");
  }).catch((err) => {
    console.log("Hubo un error con los campos de tarjeta: ", err);
  });
});

Métodos en campos de tarjeta individuales

Los siguientes métodos son soportados en campos de tarjeta individuales:

addClass()
clear()
focus()
removeAttribute()
removeClass()
render()
setAttribute()
setMessage()
close()

Método

Descripción

addClass() -> {promise | void}

Añade una clase a un campo. Usa este método para actualizar estilos de campo cuando ocurren eventos en otro lugar durante el pago.

clear() -> {void}

Limpia el valor del campo.

focus() -> {void}

Enfoca el campo.

removeAttribute() -> {promise | void}

Elimina un atributo de un campo donde se llama Puedes eliminar los siguientes atributos con removeAttribute:

aria-invalid
aria-required
disabled
placeholder

removeClass() -> {promise | void}

Pasa el nombre de la clase como una cadena en removeClass para eliminar una clase de un campo. Usa este método para actualizar estilos de campo cuando ocurren eventos en otro lugar en el flujo de pago.

render() -> {promise | void}

Renderiza los campos de tarjeta individuales al DOM para el pago. Pasa la referencia del elemento HTML o la cadena del selector CSS para el campo de entrada.

setAttribute() -> {promise | void}

Establece los atributos y valores soportados de un campo. Pasa atributos y valores como cadenas.

setMessage() -> {void}

Establece un mensaje en un campo para lectores de pantalla. Pasa el mensaje como una cadena en setMessage.

`addClass()`

const cardField = paypal.CardFields(/* options */)
const numberField = cardField.NumberField(/* options */)
numberField.addClass("purple");
numberField.render(cardNumberContainer);

`clear()`

const cardField = paypal.CardFields(/* options */)
const nameField = cardField.NameField(/* options */);
nameField.render(cardNameContainer);
nameField.clear();

`focus()`

const cardField = paypal.CardFields(/* options */)
const nameField = cardField.NameField(/* options */)
nameField.render(cardNameContainer);
nameField.focus();

`removeAttribute()`

const cardField = paypal.CardFields(/* options */)
const numberField = cardField.NumberField(/* options */)
numberField.render(cardNumberContainer);
numberField.removeAttribute("placeholder");

`removeClass()`

const cardField = paypal.CardFields(/* options */)
const numberField = cardField.NumberField(/* options */)
numberField.render(cardNumberContainer);
numberField.removeClass("purple");

`render()`

const cardNumberContainer = document.getElementById("card-number-field-container");
const cardField = paypal.CardFields(/* options */)
cardField.NumberField(/* options */).render(cardNumberContainer);
// O usar una cadena de selector
cardField.NumberField(/*options*/).render("#card-number-field-container")

`setAttribute()`

const cardField = paypal.CardFields(/* options */)
const nameField = cardField.NameField(/* options */)
nameField.setAttribute("placeholder", "Ingresa tu nombre completo");
nameField.render(cardNameContainer);

`setMessage()`

const cardField = paypal.CardFields(/* options */)
const nameField = cardField.NameField(/* options */)
nameField.render(cardNameContainer);
nameField.setMessage("Ingresa tu nombre completo");

Type definitions

cardSecurityCode
cardType
cardFieldData
stateObject

cardSecurityCode

Información sobre el código de seguridad de una tarjeta.

Propiedad

Tipo

Descripción

name

String

El nombre de un código de seguridad para una tarjeta. Los valores válidos son CVV, CID y CVC.

size

Number

La longitud esperada del código de seguridad, típicamente 3 o 4 dígitos.

cardType

Información sobre el tipo de tarjeta enviada en el array cards como parte del stateObject.

Propiedad

Tipo

Descripción

type

String

El tipo de tarjeta legible por código. Los valores válidos son:

american-express
diners-club
discover
jcb
maestro
mastercard
unionpay
visa
elo
hiper, hipercard

code

Object cardSecurityCode

Contiene datos sobre los requisitos de código de seguridad de la marca de la tarjeta. Por ejemplo, en una tarjeta Visa, el CVV es 3 dígitos. En una tarjeta American Express, el CID es 4 dígitos.

niceType

String

El tipo de tarjeta legible por humanos. Los valores válidos son:

American Express
Diner Club
discover
JCB
Maestro
Mastercard
UnionPay
Visa
Elo
Hiper,Hipercard

cardFieldData

Los datos de campo para pagos con tarjeta se envían para cada campo de tarjeta en el stateObject.

Propiedad

Tipo

Descripción

isFocused

Boolean

Muestra si el campo de entrada está actualmente enfocado.

isEmpty

Boolean

Muestra si el usuario ha ingresado un valor en la entrada.

isPotentiallyValid

Boolean

Muestra si la entrada actual puede ser válida. Por ejemplo, si un pagador ingresa 41 para el número de tarjeta, la entrada puede volverse válida. Sin embargo, si el pagador ingresa 4x, la entrada no puede volverse válida.

isValid

Boolean

Muestra si la entrada es válida y puede ser enviada.

stateObject

cards

Array de cardType

Devuelve un array de tarjetas potenciales. Si se ha determinado el tipo de tarjeta, el array contiene solo 1 tarjeta.

emittedBy

String

El nombre del campo asociado con un evento. emittedBy no se incluye si es devuelto por getState. Los valores válidos son "name","number", "cvv", y "expiry".

errors

Array

Array de campos de tarjeta que actualmente no son válidos. Los valores potenciales son "INELIGIBLE_CARD_VENDOR","INVALID_NAME", "INVALID_NUMBER", "INVALID_EXPIRY"o "INVALID_CVV".

isFormValid

Boolean

Muestra si el formulario es válido.

fields

Object

Contiene datos sobre el campo en el contexto del evento. Los valores válidos son "cardNameField", "cardCvvField", "cardNumberField"y "cardExpiryField". Cada una de estas claves contiene un objeto de tipo cardFieldData.

Ejemplo completo

El siguiente ejemplo muestra cómo podría aparecer un script completo de campos de tarjeta alojados en HTML:

<html>
    <head>
        <meta charset="UTF-8">
        <title>Página de Pago</title>
    </head>
    <body>
        <div id="checkout-form">
         <div id="card-name-field-container"></div>
         <div id="card-number-field-container"></div>
         <div id="card-expiry-field-container"></div>
         <div id="card-cvv-field-container"></div>
         <button id="multi-card-field-button" type="button">Pagar ahora con Campos de Tarjeta</button>
        </div>
    </body>
      <script src="https://www.paypal.com/sdk/js?client-id=<your-client-id>&components=card-fields"></script>
      <script>
       // Objeto de estilos personalizado (opcional)
        const styleObject = {
            input: {
                "font-size": "16 px",
                "font-family": "monospace",
                "font-weight": "lighter",
                color: "blue",
            },
            ".invalid": {
            color: "purple",
            },
            ":hover": {
                color: "orange",
            },
            ".purple": {
                color: "purple",
            },
        };
        // Crear el componente de campos de tarjeta y definir funciones de devolución
        const cardField = paypal.CardFields({
            style: styleObject,
            createOrder: function (data, actions) {
                return fetch("/api/paypal/order/create/", {
                method: "post",
                })
                .then((res) => {
                    return res.json();
                })
                .then((orderData) => {
                    return orderData.id;
                });
            },
            onApprove: function (data, actions) {
                const { orderID } = data;
                return fetch('/api/paypal/orders/${orderID}/capture/', {
                method: "post",
                })
                .then((res) => {
                    return res.json();
                })
                .then((orderData) => {
                    // Redirigir a la página de éxito
                });
            },
            inputEvents: {
                onChange: function (data) {
                    // Manejar un evento de cambio en cualquiera de los campos
                },
                onFocus: function(data) {
                    // Manejar un evento de foco en cualquiera de los campos
                },
                onBlur: function(data) {
                    // Manejar un evento de desenfoque en cualquiera de los campos
                },
                onInputSubmitRequest: function(data) {
                    // Manejar un intento de enviar el formulario de tarjeta completo
                    // mientras se enfoca cualquiera de los campos
                }
            },
        });
        // Definir el contenedor para cada campo y el botón de envío
        const cardNameContainer = document.getElementById("card-name-field-container"); // Campo opcional
        const cardNumberContainer = document.getElementById("card-number-field-container");
        const cardCvvContainer = document.getElementById("card-cvv-field-container");
        const cardExpiryContainer = document.getElementById("card-expiry-field-container");
        const multiCardFieldButton = document.getElementById("multi-card-field-button");
        // Renderizar cada campo después de verificar la elegibilidad
        if (cardField.isEligible()) {
            const nameField = cardField.NameField();
            nameField.render(cardNameContainer);
            const numberField = cardField.NumberField();
            numberField.render(cardNumberContainer);
            const cvvField = cardField.CVVField();
            cvvField.render(cardCvvContainer);
            const expiryField = cardField.ExpiryField();
            expiryField.render(cardExpiryContainer);
            // Añadir listener de clic al botón de envío y llamar a la función submit en el componente CardField
            multiCardFieldButton.addEventListener("click", () => {
                cardField
                .submit()
                .then(() => {
                    // Manejar un pago exitoso
                })
                .catch((err) => {
                    // Manejar un pago fallido
                });
            });
        }
      </script>
</html>

Elegibilidad de financiación

Los botones de pago renderizan automáticamente todos los botones elegibles en una sola ubicación en tu página por defecto.

Si tu caso de uso lo permite, puedes renderizar botones individuales e independientes para cada método de pago soportado. Por ejemplo, renderizar los botones de PayPal, Venmo, PayPal Credit y métodos de pago alternativos en diferentes partes de la página de pago, junto a diferentes botones de radio, o en páginas completamente diferentes.

Incluso con botones independientes, tus integraciones aprovechan la lógica de elegibilidad que proporciona el SDK de JavaScript de PayPal, lo que significa que solo los botones apropiados para el comprador actual se muestran automáticamente.

<script src="https://www.paypal.com/sdk/js?client-id=YOUR_CLIENT_ID&components=funding-eligibility"></script>

Paypal.rememberFunding( fundingSources )

Cuando el cliente elige guardar una fuente de financiación, esa fuente se almacena y está disponible para usar en pagos futuros.

paypal.rememberFunding([ paypal.FUNDING.VENMO ]);

paypal.getFundingSources

Recorre las fuentes de financiación y métodos de pago.

paypal.getFundingSources().forEach(function(fundingSource) {
// ...
});

paypal.isFundingEligible( fundingSource )

Verifica la elegibilidad de financiación de las fuentes de financiación actuales.

paypal.isFundingEligible(fundingSource);

Financiación

Esta tabla incluye las fuentes de financiación disponibles. Los botones de pago renderizan automáticamente todos los botones elegibles en una sola ubicación en tu página por defecto. Si necesitas anular esto, puedes especificar los botones que quieres mostrar siguiendo la guía de Botones de pago independientes.

Fuente de financiación

Botón de pago

paypal.FUNDING.PAYPAL

PayPal

paypal.FUNDING.CARD

Tarjetas de crédito o débito

paypal.FUNDING.CREDIT

PayPal Credit

paypal.FUNDING.VENMO

Venmo

paypal.FUNDING.SEPA

SEPA-Lastschrift

paypal.FUNDING.BANCONTACT

Bancontact

paypal.FUNDING.EPS

eps

paypal.FUNDING.GIROPAY

giropay (Legacy) *

paypal.FUNDING.IDEAL

iDEAL

paypal.FUNDING.MERCADOPAGO

Mercado Pago

paypal.FUNDING.MYBANK

MyBank

paypal.FUNDING.P24

Przelewy24

paypal.FUNDING.SOFORT

SOFORT (Legacy) *

Importante: giropay fue descontinuado el 30 de junio de 2024. PayPal no admitirá pagos con giropay a partir del 1 de julio de 2024. Ofrece a tus usuarios PayPal wallet y otros métodos de pago alternativos. Más información .

Importante: Sofort fue descontinuado el 18 de abril de 2024. PayPal no admitirá pagos con Sofort a partir del 19 de abril de 2024. Ofrece a tus usuarios PayPal wallet y otros métodos de pago alternativos. Más información .

Mensajes

Usa cuando quieras mostrar mensajes de Pago Posterior en tu sitio. Debido a que las ofertas de Pago Posterior difieren por país, ciertas opciones para el componente messages se renderizan de manera diferente dependiendo de la ubicación del comprador. Para detalles completos, así como ejemplos específicos por país, consulta la Referencia de Pago Posterior.

Ver también

AnteriorTrackers SiguienteGuía de integración

Última actualización hace 5 días

¿Te fue útil?