krugerdavid/laravel-bancard

Laravel integration for Bancard VPOS 2.0 (Single Buy, Cards, Charge)

v1.0.0 2026-03-09 20:24 UTC

Requires

• php: ^8.1
• guzzlehttp/guzzle: ^7.0
• illuminate/support: ^10.0|^11.0

Requires (Dev)

• orchestra/testbench: ^8.0|^9.0
• pestphp/pest: ^2.0
• pestphp/pest-plugin-laravel: ^2.0

MIT

• David Kruger

• payments
• laravel
• vpos
• Paraguay
• bancard
• krugerdavid

README

Laravel integration for Bancard VPOS 2.0 (Single Buy, Cards, Charge). Basado en la documentación oficial Bancard eCommerce Single Buy v1.22.

Requisitos

• PHP 8.1+
• Laravel 10, 11 o 12
• GuzzleHTTP 7.x

Instalación

composer require krugerdavid/laravel-bancard

Configuración

Publicar la config:

php artisan vendor:publish --tag=bancard-config

Variables de entorno (.env):

BANCARD_PUBLIC_KEY=tu_clave_publica_32_caracteres
BANCARD_PRIVATE_KEY=tu_clave_privada_40_caracteres
BANCARD_STAGING=true
BANCARD_TIMEOUT=30

Uso

Pago ocasional (Single Buy)

Inicia un pago y obtén el process_id para el iframe de checkout:

use KrugerDavid\Bancard\Facades\Bancard;

$result = Bancard::singleBuy(
    shopProcessId: 54322,
    amount: '10330.00',
    description: 'Ejemplo de pago',
    returnUrl: 'https://tusitio.com/finish'
);

// $result['process_id'] → usar en Bancard.Checkout.createForm()
// $result['status'] → 'success'

Opciones adicionales:

Bancard::singleBuy(54322, '10330.00', 'Pago', 'https://x.com/finish', [
    'cancel_url' => 'https://x.com/cancel',
    'additional_data' => '099VS ORO000045',  // promociones
    'iva_amount' => '1033.00',
    'preauthorization' => 'S',
    'extra_response_attributes' => ['payment_card_type'],
]);

Pago con Zimple

$result = Bancard::singleBuyZimple(
    shopProcessId: 54322,
    amount: '10330.00',
    description: 'Pago Zimple',
    returnUrl: 'https://tusitio.com/finish',
    userPhone: '0981123456'
);

Iframe de checkout

Incluir el script e inicializar el formulario:

<script src="{{ Bancard::getCheckoutScriptUrl() }}"></script>
<div id="iframe-container"></div>
<script>
  window.onload = function() {
    Bancard.Checkout.createForm('iframe-container', '{{ $processId }}', {});
  };
</script>

Librería: bancard-checkout-js

Rollback (reversa)

$result = Bancard::rollback(12313);
// $result['status'] === 'success'

Consultar confirmación

$result = Bancard::getConfirmation(12313);
// $result['confirmation']['response'] → 'S' (aprobado) o 'N'
// $result['confirmation']['response_code'] → '00' (aprobada)

Catastro de tarjeta (Cards New)

$result = Bancard::cardsNew(
    cardId: 1,
    userId: 966389,
    userCellPhone: '0919876543',
    userMail: '[e-mail]',
    returnUrl: 'https://tusitio.com/cards/result'
);
// Usar $result['process_id'] con Bancard.Cards.createForm()

Listar tarjetas del usuario

$result = Bancard::usersCards(966389);
// $result['cards'] → array de tarjetas con alias_token

Pago con token (Charge)

$result = Bancard::charge(
    60361,
    '723215.00',
    $aliasToken,  // de usersCards
    [
        'return_url' => 'https://tusitio.com/result',
        'number_of_payments' => 1,
    ]
);

Eliminar tarjeta

$result = Bancard::deleteCard(966389, $aliasToken);

Verificar token de confirmación (webhook)

Bancard envía un POST a tu URL de confirmación. Verifica el token:

$isValid = Bancard::verifyConfirmToken(
    $shopProcessId,
    $amount,
    $receivedToken
);

Inyección de dependencias

use KrugerDavid\Bancard\BancardManager;

class PaymentController
{
    public function __construct(
        private BancardManager $bancard
    ) {}

    public function checkout()
    {
        $result = $this->bancard->singleBuy(...);
    }
}

Factura electrónica (Billing)

Para enviar datos de facturación:

use KrugerDavid\Bancard\DTOs\Billing;
use KrugerDavid\Bancard\DTOs\BillingDetail;

$billing = new Billing(
    clientRuc: '123456-1',
    clientName: 'JUAN GONZALEZ',
    clientEmail: '[e-mail]',
    commerceStamp: '12559969',
    commerceExpeditionPoint: '001',
    commerceEstablishment: '002',
    details: [
        new BillingDetail('Item 1', '10000.00', 10, 1),
        new BillingDetail('Item 2', '330.00', 10, 1),
    ]
);

Bancard::singleBuy(54322, '10330.00', 'Pago', 'https://x.com', [
    'billing' => $billing,
]);

Operaciones implementadas

Operación	Endpoint	Método
Single Buy	single_buy	POST
Single Buy Zimple	single_buy	POST
Rollback	single_buy/rollback	POST
Get Confirmation	single_buy/confirmations	POST
Cards New	cards/new	POST
Users Cards	users/{id}/cards	POST
Charge	charge	POST
Delete Card	users/{id}/cards	DELETE

Créditos

• David Krüger

Licencia

MIT