Solana Pay: todo lo que necesitas saber

Solana Pay: cómo funciona

Solana Pay ofrece una forma diferente de interactuar con contratos inteligentes y transferir tokens. En lugar de conectar una billetera, los usuarios pueden ver y firmar una transacción mediante un enlace. Esto elimina la barrera de tener que conectar una billetera para interactuar. Funciona tanto para pagos simples como para interacciones con aplicaciones, por lo que puede gestionar solicitudes de transacción y solicitudes de transferencia.

La función principal de Solana Pay es Transfer Request, una solicitud no interactiva para transferir SOL o tokens SPL. Es importante señalar que no todas las billeteras de Solana aceptan este formato. Sin embargo, la mayoría de las billeteras populares sí lo hacen (Phantom, Solflare y Glow). Así se ve la URL de una solicitud de transferencia de Solana Pay:

solana:<recipient>?amount=<amount>&spl-token=<spl-token>&reference=<reference>&label=<label>&message=<message>&memo=<memo>

Una billetera utiliza los parámetros de la URL para crear directamente una transacción. En esta guía nos centraremos en las solicitudes de transferencia, pero es importante señalar que casi cualquier transacción de Solana puede convertirse en una URL válida de Solana Pay.

Parámetros

Ahora veamos en detalle cada uno de los parámetros:

Destinatario:

Es la clave pública de la persona a la que envías SOL. Para transferencias de tokens SPL, especifica el tipo de token en el campo spl-token. La billetera usa esta información para determinar la cuenta real de la transferencia.

Cantidad

La cantidad de SOL o tokens que envías. Si es menor que 1, debe incluir un 0 antes del punto decimal. Si no se indica una cantidad, la billetera te pedirá que la ingreses. Si transfieres SOL, esta cantidad se expresa en SOL, no en lamports.

Token SPL

Este campo opcional representa la dirección de mint de un tipo específico de cuenta de token SPL. Si no lo incluyes, la transacción será una transferencia normal de SOL.

Referencia

Un identificador único codificado en la transacción. Se utiliza para encontrar transacciones específicas y verificar sus resultados.

Etiqueta

Una descripción breve del origen de la solicitud de transferencia. Podría ser una tienda o una aplicación. Las billeteras se la muestran al usuario para proporcionar información sobre la transacción.

Mensaje

Una URL codificada que almacena detalles sobre el motivo de la transferencia. Podría incluir lo que compras, el ID de un pedido o una nota breve. Las billeteras también la utilizan para ofrecer más contexto al usuario.

Memo

Una nota incluida en la transacción de pago. No debe contener información privada ni confidencial, ya que se almacena on-chain.

Estos detalles te dan control total sobre tu transacción y simplifican la interacción entre tu billetera y el destinatario. Por seguridad, las aplicaciones solo deben procesar la transacción cuando se haya confirmado on-chain.

Solana Pay: URLs de ejemplo

Enviar 0.5 SOL:

solana:CckxW6C1CjsxYcXSiDbk7NYfPLhfqAm3kSB5LEZunnSE?amount=0.5&label=Amazon&message=Thanks%20for%20shopping%20at%20Amazon&memo=ID321

Enviar 5 USDC:

solana:CckxW6C1CjsxYcXSiDbk7NYfPLhfqAm3kSB5LEZunnSE?amount=5&spl-token=EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v

Solana Pay: implementación con Next.js

¿Qué vamos a crear? Al final de este tutorial, tendrás una aplicación web que crea un código QR de Solana Pay a partir de los datos que ingresan los usuarios (una dirección de billetera y una cantidad de SOL). Esta aplicación también mostrará el estado del pago mediante comprobaciones del estado de la transacción en la blockchain.

Requisitos previos

• Debes tener Node.js instalado en tu equipo
• Debes tener buenos conocimientos de React y TypeScript.
• Necesitarás una billetera de Solana para enviar y recibir fondos.
• También necesitarás una clave de API de Helius para cualquier operación on-chain. Puedes obtener gratis una clave de API de Helius con solo una billetera en nuestro portal para desarrolladores.

Pasos

Sigue estos pasos para usar Solana Pay con Next.js.

Crea una aplicación de Next.js

Primero, asegúrate de que Node esté instalado y luego crea la aplicación de Next.js. Escribe lo siguiente en la terminal:

npx create-next-app@latest sol-pay-app

‍A continuación, aparecerán varias preguntas. Puedes seleccionar estas opciones:

Una vez creada, puedes acceder al directorio con:

cd sol-pay-app

Una vez dentro del directorio, puedes iniciar la aplicación con:

npm run dev

Ve a http://localhost:3000/ para ver tu aplicación.

Instala los paquetes

Esta aplicación requiere dos paquetes: Solana web3.js y Solana Pay. También utilizaremos un paquete llamado “react-qr-code” para generar versiones en código QR de los enlaces de las transacciones.

Para instalar estos paquetes, ejecuta:

npm install @solana/pay @solana/web3.js bignumber.js react-qr-code --save

Crea el frontend

Crea un frontend para mostrar el código QR de Solana Pay y permitir cambios en la dirección que recibirá los SOL y en la cantidad de SOL. Por seguridad, se recomienda ejecutar toda la lógica en el backend, en especial la configuración de las cantidades y del destinatario.

Sin embargo, para simplificar las cosas, también ejecutaremos la lógica de la aplicación en el frontend.

1. Ve al directorio pages y abre el archivo index.tsx. Este archivo representa tu página de inicio. Reemplaza el código existente por el siguiente:

export default function Home() {
  return (
    <div className="flex flex-col items-center justify-center min-h-screen bg-gray-100">
      <h1 className="mb-6 text-3xl font-bold text-orange-700">
        Helius Solana Pay Demo
      </h1>
    </div>
  );
}

2. Agrega las importaciones en la parte superior de la página.

// imports
import {Cluster,clusterApiUrl,Connection,PublicKey,Keypair} from "@solana/web3.js";
import { encodeURL, createQR,findReference, FindReferenceError, validateTransfer } from "@solana/pay";
import BigNumber from "bignumber.js";
import { useState } from "react";
import QRCode from "react-qr-code";

3. Crea una variable para almacenar tu URL RPC de Helius. Si planeas implementar esta aplicación, debes usar un archivo ENV o un proxy para ocultar tu clave de API.

// get a free Helius RPC at helius.dev
 const RPC="https://rpc.helius.xyz/?api-key="!

4. Crea un objeto Solana Connection con tu URL RPC de Helius:

console.log('Connecting to the Solana network\n');
const connection = new Connection(RPC, 'confirmed');

5. A continuación, declararemos e inicializaremos las variables que utilizaremos. Esto incluye todas las variables necesarias en la URL de Solana Pay. Puedes crear estas variables dentro de la función Home().

// URL Variables
  const [address, setAddress] = useState("");
  const [recipient, setRecipient] = useState(
    new PublicKey("CckxW6C1CjsxYcXSiDbk7NYfPLhfqAm3kSB5LEZunnSE"));
  const [amount, setAmount] = useState(new BigNumber(1));
  const [message, setMessage] = useState("Helius Demo Order");
  const reference = new Keypair().publicKey;
  const label = "Helius Super Store";
  const memo = "Helius#4098";

  // for the QR code
  const [qrCodeValue, setQrCodeValue] = useState('');
  const [paymentStatus, setPaymentStatus] = useState('');

6. Ahora debemos escribir una función para crear el pago. Esta función tomará las variables de los campos de entrada y creará una URL codificada de Solana Pay con el método encodedURL. Después, convertiremos el objeto URL en una cadena y la guardaremos para mostrar el código QR más adelante. Agrega el siguiente código debajo de las variables:

async function createPayment() {
    console.log("Creating a payment URL \n");
    setRecipient(new PublicKey(address));
    const url = encodeURL({
      recipient,
      amount,
      reference,
      label,
      message,
      memo,
    });

    setQrCodeValue(url.toString()); // convert URL object to string
    checkPayment();
  }

7. Una vez creado el pago, mostraremos el código QR al usuario para que pueda escanearlo y realizar la transacción. Para verificar si la transacción se realizó correctamente, debemos crear una función que compruebe la transacción de pago on-chain. En la función createPayment anterior, puedes ver que llamamos a esta función justo después de crear la transacción.

async function checkPayment() {
    // update payment status
    setPaymentStatus('pending');

		// search for transaction

		// validate transaction
}

Esta función tendrá dos partes: buscar la transacción confirmada y validarla.

Como el usuario interactuará con la transacción desde otro dispositivo, no hay forma de saber exactamente cuándo se realizó. En su lugar, comprobaremos repetidamente si ocurrió una transacción con la referencia correspondiente y cuál es su estado. Esto se hace con el método findReference de Solana Pay.

// search for transaction
console.log('Searching for the payment\n');
    let signatureInfo;
  
    const {signature} = await new Promise((resolve, reject) => {
      
        const interval = setInterval(async () => {
            console.count('Checking for transaction...'+reference);
            try {
                signatureInfo = await findReference(connection, reference, { finality: 'confirmed' });
                console.log('\n Signature: ', signatureInfo.signature,signatureInfo);
                clearInterval(interval);
                resolve(signatureInfo);
            } catch (error: any) {
                if (!(error instanceof FindReferenceError)) {
                    console.error(error);
                    clearInterval(interval);
                    reject(error);
                }
            }
        }, 250);
    });
	// Update payment status
  setPaymentStatus('confirmed');

Una vez encontrada la transacción, debemos asegurarnos de que todo haya ocurrido correctamente.

Esto incluye comprobar que el destinatario correcto recibió los tokens y que se envió la cantidad correcta. Para hacerlo, utilizaremos el método validateTransfer de Solana Pay:

//validate transaction
    console.log('Validating the payment\n');
    try {
      await validateTransfer(connection, signature, { recipient: recipient, amount });

      // Update payment status
      setPaymentStatus('validated');
      console.log('Payment validated');
      return true;
      
  } catch (error) {
      console.error('Payment failed', error);
      return false;
  }

8. El último paso del proceso será agregar el TSX para configurar la interfaz de usuario. Utilizaremos Tailwind para dar estilo a los elementos. La interfaz incluirá un encabezado, dos campos de entrada para la dirección del destinatario y la cantidad de SOL, un botón y un código QR de Solana Pay. Una vez validado el pago, el código QR de Solana Pay se reemplazará por el texto “Pago validado”. El botón llamará al método createPayment.

//validate transaction
return (
    <div className="flex flex-col items-center justify-center min-h-screen bg-gray-100">
      <h1 className="mb-6 text-3xl font-bold text-orange-700">
        Helius Solana Pay Demo
      </h1>
      <div className="w-full max-w-md p-6 mx-auto bg-white rounded-xl shadow-md">
        <div className="mb-4">
          <label className="block mb-2 text-sm font-medium text-gray-700">
            Address:
          </label>
          <input
            type="text"
            onChange={(e) => setAddress(e.target.value)}
            className="w-full px-3 py-2 text-sm leading-tight text-gray-700 border rounded shadow appearance-none focus:outline-none focus:shadow-outline"
          />
        </div>
        <div className="mb-4">
          <label className="block mb-2 text-sm font-medium text-gray-700">
            Amount:
          </label>
          <input
            type="number"
            onChange={(e) => setAmount(new BigNumber(e.target.value))}
            className="w-full px-3 py-2 text-sm leading-tight text-gray-700 border rounded shadow appearance-none focus:outline-none focus:shadow-outline"
          />
        </div>
        <div className="flex justify-center items-center">
        <button
          className="px-4 py-2 font-bold text-white bg-blue-500 rounded hover:bg-blue-700"
          onClick={createPayment}
        >
          Create QR Code
        </button>
        </div>
        
        <div>
        {paymentStatus === 'validated' ? <p className="mt-4 text-green-500 text-center">Payment Validated</p> : <div className="flex justify-center mt-4">
          {qrCodeValue && }
        </div>}
      </div>
      </div>
      
    </div>
  );

‍Cuando hayas completado todos estos pasos, tendrás una aplicación que se verá y funcionará así:

Solana Pay: crea experiencias fluidas

Ya sea que realices un pago o configures una transacción, el sistema de codificación de Solana Pay ofrece una experiencia fluida tanto para los usuarios como para las aplicaciones. Espero que esta guía te sirva como una herramienta completa para comprender e implementar Solana Pay y hacer que tus interacciones con la blockchain de Solana sean más fluidas y eficientes. Si necesitas ayuda, únete al Discord de Helius o contáctanos en Twitter.

• Consulta el código completo que debe incluirse en el archivo index.tsx
• Obtén más información sobre Solana Pay
• Consulta la documentación de Solana Pay

‍

‍

‍