README

Implementación del Botón de Pago Yappy para Laravel.

Este paquete está basado en la Librería en PHP del sitio web de Banco General y nació porque a muchos no nos agrada la idea de versionar librerías.

Instalación

Para instalar, utiliza el siguiente comando:

composer require shino47/laravel-yappy-checkout

Si tienes Laravel 5.5 o superior, esto es todo (gracias al auto-discovery). Para versiones anteriores tienes agregar unas líneas a tu archivo config/app.php, dentro de la llave providers y dentro de aliases:

'providers' => [
    // Otros paquetes por acá
    // ...
    BancoGeneral\YappyCheckout\YappyCheckoutServiceProvider::class,
],

'aliases' => [
    // Otros aliases por acá
    // ...
    'YappyCheckout' => BancoGeneral\YappyCheckout\Facades\YappyCheckoutFacade::class,
],

Configuración

Agrega las siguientes variables a tu .env (y a tu .env.example en blanco si eres un buen muchacho):

YAPPY_SECRET_KEY=
YAPPY_MERCHANT_ID=
YAPPY_MERCHANT_URL=
YAPPY_SUCCESS_URL=
YAPPY_FAIL_URL=
YAPPY_LOGS_ENABLED=true

Variable	Tipo	Descripción
YAPPY_SECRET_KEY	string	Clave secreta del comercio.
YAPPY_MERCHANT_ID	string	ID del comercio.
YAPPY_MERCHANT_URL	string	URL de comercio. Normalmente es igual a APP_URL, pero en ambientes de desarrollo APP_URL puede tomar valores locales.
YAPPY_SUCCESS_URL	string	URL a la cual se redireccionará al usuario cuando se ejecute correctamente la transacción.
YAPPY_FAIL_URL	string	URL a la cual se redireccionará al usuario en caso de que cancele la transacción o haya algún error.
YAPPY_LOGS_ENABLED	bool	Indica si registra errores en los logs. Por defecto es true.

Si quieres tener más control sobre la configuración, puedes hacer publish del archivo de configuración:

php artisan vendor:publish --provider="BancoGeneral\YappyCheckout\YappyCheckoutServiceProvider"

Esto agregará el archivo config/yappy.php y el public/vendor/yappy/js/yappy-checkout.js a tu proyecto.

Si no quieres ambos archivos, puedes usar los tags config y assets:

# Si sólo necesitas el archivo de configuración
php artisan vendor:publish \
    --provider="BancoGeneral\YappyCheckout\YappyCheckoutServiceProvider" \
    --tag=config

# Si sólo necesitas los assets para el front end
php artisan vendor:publish \
    --provider="BancoGeneral\YappyCheckout\YappyCheckoutServiceProvider" \
    --tag=assets

Uso

El flujo del pago es sencillo y se resume en lo siguiente:

1. El usuario presiona el botón de Pagar/Donar.
2. Nuestra aplicación recibe la petición, valida las credenciales del comercio y genera la URL del pago.
3. Si todo sale bien, el usuario es redireccionado a la URL generada. Ya aquí el usuario está fuera de nuestra aplicación. El flujo continúa del lado de Yappy.
4. Luego de que se haga, falle o cancele la transacción, el usuario será redirigido a la URL definida en YAPPY_SUCCESS_URL o YAPPY_FAIL_URL. Yappy nos hará una petición a un endpoint de nuestra aplicación.
5. En esta petición Yappy nos envía el número de orden y el estado de la transacción. Somos libres de jugar con esta información en nuestra aplicación.

Agregar el botón a nuestras vistas

Primero, agregamos lo siguiente en donde queramos nuestro botón.

<!-- Este es un botón con el tema por defecto y dice Pagar -->
<button type="submit">
    <div id="Yappy_Checkout_Button"></div>
</button>

<!-- Este es un botón con el tema oscuro y dice Donar -->
<a href="/pagar-con-yappy">
    <div
        id="Yappy_Checkout_Button"
        data-color="dark"
        data-donacion
    ></div>
</a>

Lamentablemente, hicieron que el botón por fuerza sea un div (en el CSS). En nuestro caso, no nos vamos a complicar y vamos en envolver ese div en una etiqueda a o button.

Como vemos, el botón acepta atributos de tipo data.

Atributo	Descripción
color	Define el color del botón. Las opciones son dark y brand (por defecto).
donacion	Define el texto del botón. Por defecto es Pagar, pero si está presente dirá Donar.

Lo siguiente será agregar el script que le dará estilo a nuestro botón. Podemos hacerlo de alguna de las siguientes maneras.

Usando un CDN

<!-- Para la versión 1.0.1 -->
<script src="https://cdn.jsdelivr.net/gh/shino47/laravel-yappy-checkout@1.1.1/resources/assets/js/yappy-checkout.js"></script>

<!-- Para la última versión. Inestable, sólo para machotes. -->
<script src="https://cdn.jsdelivr.net/gh/shino47/laravel-yappy-checkout@main/resources/assets/js/yappy-checkout.js"></script>

Usando el generado en el vendor:publish

Si hiciste vendor:publish ya tienes este script en la carpeta public/vendor/yappy/js, por lo que podemos referenciarlo así:

<script src="{{ asset('vendor/yappy/js/yappy-checkout.js') }}"></script>

Usando Laravel Mix

El método anterior tiene un inconveniente: si se actualiza, el cliente no lo notará si el navegador no refresca el cache. Para solucionar eso, nos apoyamos en Laravel Mix. Abrimos el archivo webpack.mix.js de nuestra aplicación y agregamos lo siguiente:

mix.scripts([
    // Otras librerías por acá...
    // ...
    'vendor/shino47/laravel-yappy-checkout/resources/assets/js/yappy-checkout.js',
], 'public/js/vendor.js');

Y en nuestras vistas:

<script src="{{ asset(mix('js/vendor.js')) }}"></script>

Redireccionar al cliente

Una vez el usuario haya presionado el enlace o botón, la petición será recibida en nuestro controlador de la siguiente manera.

use YappyCheckout;

class YeyoController extends Controller
{
    public function redirectToYappyPayment()
    {
        $url = YappyCheckout::getPaymentUrl($orderId, $subtotal, $tax, $total);
        abort_if(is_null($url), 500);
        return redirect()->away($url);
    }
}

El método getPaymentUrl devuelve null si ha habido un error generando la URL; en ese caso verifica las credenciales del comercio. Este método recibe los siguientes parámetros:

Variable	Tipo	Descripción
orderId	string, int	ID de la orden. Será usada por Yappy al finalizar la transacción.
subtotal	float	Subtotal de la compra.
tax	float	Impuesto de la compra.
total	float	Total de la compra.
phone	string	El número de teléfono del usuario (opcional).

Si todo sale bien, el usuario será redirigido a esa URL generada.

Páginas de estado

Una vez que se haya hecho o se cancele la transacción, el usuario será redirigido a nuestro sitio web. Para ello, debemos definir las variables YAPPY_SUCCESS_URL y YAPPY_FAIL_URL. Pueden ser, por ejemplo:

YAPPY_SUCCESS_URL="${APP_URL}/pago-recibido"
YAPPY_FAIL_URL="${APP_URL}/pago-fallido"

Recuerda definir esas rutas en tu routes/web.php y crearles sus vistas.

Recibir el estado de la transacción

Una vez terminada la transacción, Yappy nos enviará el estado a nuestro servidor a mi-dominio.com/pagosbg.php. Lamentablemente, no podemos cambiar esa ruta, así que toca trabajar con ese .php feíto en la URL.

Creamos nuestra ruta en routes/web.php.

// Para Laravel 8 en adelante
Route::get('/pagosbg.php', [YeyoController::class, 'yappyPaymentStatus']);

// O para versiones anteriores
Route::get('/pagosbg.php', 'YeyoController@yappyPaymentStatus');

Y en nuestro controlador.

use YappyCheckout;
use Illuminate\Http\Request;

class YeyoController extends Controller
{
    public function yappyPaymentStatus(Request $request)
    {
        $data = YappyCheckout::getPaymentStatus($request->all());
        $success = isset($data);
        if ($success) {
            // Mi lógica de negocio a continuación
            $order = \App\Models\Order::find($data['order_id']);
            $order->status = $data['status'];
            $order->save();
        }
        return response()->json([
            'success' => $success,
        ]);
    }
}

El método getPaymentStatus recibe un array con los parámetros de la petición y devuelve null en caso de error o un array con el ID de la orden (order_id) y el estado de la transacción (status). Los valores de status pueden ser:

Código	Descripción
E	Ejecutado. El cliente confirmó el pago y se completó la compra.
R	Rechazado. El cliente no confirma el pago dentro de los cinco minutos que dura la vida del pedido.
C	Cancelado. El cliente inició el proceso, pero canceló el pedido en el app de Banco General.

Nota: Yappy no está enviando peticiones cuando las transacciones quedan rechazadas (R). El tiempo de espera actualmente es cinco minutos, así que pasado este tiempo tendrás que actualizar el estado a rechazado.

Contribuir

Si deseas contribuir, siéntete libre de subir tu pull request usando el estándar PSR-2 que es el que usa Laravel.

Usa inglés para el código y español para documentar. Código en inglés para que combine con tus aplicaciones Laravel y documentación en español, porque hay muchos desarrolladores con inglés malito.