PHPackages                             hds-solutions/bancard-sdk - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. hds-solutions/bancard-sdk

ActiveLibrary

hds-solutions/bancard-sdk
=========================

Bancard SDK library

v1.1.3(1y ago)7742↓50%2GPL-3.0PHPPHP >=8.0

Since Feb 24Pushed 1y ago1 watchersCompare

[ Source](https://github.com/hschimpf/bancard-sdk)[ Packagist](https://packagist.org/packages/hds-solutions/bancard-sdk)[ RSS](/packages/hds-solutions-bancard-sdk/feed)WikiDiscussions main Synced 1mo ago

READMEChangelog (5)Dependencies (4)Versions (6)Used By (0)

Bancard SDK
===========

[](#bancard-sdk)

A comprehensive PHP SDK for integrating [Bancard vPOS](https://www.bancard.com.py/vpos) and [Bancard VentasQR](https://comercios.bancard.com.py/productos/ventas-qr) payment solutions into your applications.

[![Latest stable version](https://camo.githubusercontent.com/31a52d6140c3ec49f263765e7987851101a64c599e2ac33a7becbcd5a140de1c/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f6864732d736f6c7574696f6e732f62616e636172642d73646b3f7374796c653d666c61742d737175617265266c6162656c3d6c617465737426636f6c6f723d303039324342)](https://github.com/hschimpf/bancard-sdk/releases/latest)[![License](https://camo.githubusercontent.com/a38570543ded1a18ea19bacce775774b723b051360dd14b235a9ea9a6b515033/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f6c6963656e73652f68736368696d70662f62616e636172642d73646b3f7374796c653d666c61742d73717561726526636f6c6f723d303039363634)](https://github.com/hschimpf/bancard-sdk/blob/main/LICENSE)[![Total Downloads](https://camo.githubusercontent.com/d81c45e4a9b68cd231b931b926a1627976143b8bad97b6da5b10825c6762defa/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f64742f6864732d736f6c7574696f6e732f62616e636172642d73646b3f7374796c653d666c61742d73717561726526636f6c6f723d373437343734)](https://packagist.org/packages/hds-solutions/bancard-sdk)[![Monthly Downloads](https://camo.githubusercontent.com/a0e447ddcccb9a38b2e4e8480275e8a94838cb05d08c7336171620cfed0a9160/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f646d2f6864732d736f6c7574696f6e732f62616e636172642d73646b3f7374796c653d666c61742d73717561726526636f6c6f723d373437343734266c6162656c)](https://packagist.org/packages/hds-solutions/bancard-sdk)[![Required PHP version](https://camo.githubusercontent.com/a5ff04f40341979db6cc39ce1616b674cb10ddb6fae751623cb6dc822c9e2a7a/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f646570656e64656e63792d762f6864732d736f6c7574696f6e732f62616e636172642d73646b2f7068703f7374796c653d666c61742d73717561726526636f6c6f723d303036343936266c6f676f3d706870266c6f676f436f6c6f723d7768697465)](https://packagist.org/packages/hds-solutions/bancard-sdk)

Table of Contents
-----------------

[](#table-of-contents)

- [Installation](#installation)
- [Configuration](#configuration)
- [vPOS Integration](#vpos-integration)
    - [Features](#vpos-features)
    - [Usage Examples](#vpos-usage-examples)
    - [Error Handling](#error-handling)
- [VentasQR Integration](#ventasqr-integration)
    - [Features](#ventasqr-features)
    - [Usage Examples](#ventasqr-usage-examples)
- [Advanced Usage](#advanced-usage)
- [API Reference](#api-reference)
- [Contributing](#contributing)
- [License](#license)

Installation
------------

[](#installation)

### Requirements

[](#requirements)

- PHP >= 8.0

### Via composer

[](#via-composer)

```
composer require hds-solutions/bancard-sdk
```

Configuration
-------------

[](#configuration)

### Setting up Credentials

[](#setting-up-credentials)

```
use HDSSolutions\Bancard\Bancard;

// Set your vPOS API credentials
Bancard::credentials(
    publicKey:  'YOUR_PUBLIC_KEY',
    privateKey: 'YOUR_PRIVATE_KEY',
);
```

### Environment Configuration

[](#environment-configuration)

The SDK uses the staging environment by default for vPOS. Switch to production when ready:

```
use HDSSolutions\Bancard\Bancard;

// Switch to production
Bancard::useProduction();

// Or dynamically based on your application environment
Bancard::useProduction(config('app.env') === 'production');
```

vPOS Integration
----------------

[](#vpos-integration)

### vPOS Features

[](#vpos-features)

- Single payments
- Single payments through Zimple
- Card management
- Charge payments to registered cards
- Pre-authorization
- Transaction management *(get confirmation and rollback payments)*

### vPOS Usage Examples

[](#vpos-usage-examples)

#### Single Payment Flow

[](#single-payment-flow)

Endpoint used to generate a process ID to call the Bancard `` for a one-time payment.

```
use HDSSolutions\Bancard\Bancard;
use HDSSolutions\Bancard\Models\Currency;

$response = Bancard::single_buy(
    shop_process_id: $shop_process_id,
    amount:          $amount,
    description:     'Premium Subscription',
    currency:        Currency::Guarani,
    return_url:      'https://your-domain.com/payment/success',
    cancel_url:      'https://your-domain.com/payment/cancel',
);

if ($singleBuyResponse->wasSuccess()) {
    // access the generated process ID to call the Bancard
    $process_id = $singleBuyResponse->getProcessId();
}
```

#### Single Payment Flow through Zimple

[](#single-payment-flow-through-zimple)

Same as above, but for `Zimple` payments.

```
use HDSSolutions\Bancard\Bancard;
use HDSSolutions\Bancard\Models\Currency;

$singleBuyResponse = Bancard::single_buy_zimple(
    shop_process_id: $shop_process_id,
    amount:          $amount,
    description:     'Premium Subscription',
    currency:        Currency::Guarani,
    phone_no:        $phone_no, // this field is automatically send on the `additional_data` property of the request
    return_url:      'https://localhost/your-success-callback-path',
    cancel_url:      'https://localhost/your-cancelled-callback-path',
);
```

#### Card Management

[](#card-management)

1. **Register a New Card**

```
use HDSSolutions\Bancard\Bancard;

$response = Bancard::card_new(
    user_id:    $user_id,
    card_id:    $card_id,
    phone_no:   '+595991234567',
    email:      'user@example.com',
    return_url: 'https://your-domain.com/cards/callback',
);

if ($response->wasSuccess()) {
    // access the generated process ID to call the Bancard
    $processId = $response->getProcessId();
}
```

2. **List User's Cards**

```
use HDSSolutions\Bancard\Bancard;
use HDSSolutions\Bancard\Models\Card;

$response = Bancard::users_cards(
    user_id: $user_id,
);

if ($response->wasSuccess()) {
    foreach ($response->getCards() as $card) {
        echo "Card: {$card->card_masked_number}\n";
        echo "Brand: {$card->card_brand}\n";
        echo "Expiration: {$card->expiration_date}\n";
    }
}
```

3. **Charge a Registered Card**

```
use HDSSolutions\Bancard\Bancard;
use HDSSolutions\Bancard\Models\Card;
use HDSSolutions\Bancard\Models\Currency;
use HDSSolutions\Bancard\Models\Confirmation;
use HDSSolutions\Bancard\Models\SecurityInformation;

$response = Bancard::charge(
    card:            $card,
    shop_process_id: $shop_process_id,
    amount:          $amount,
    currency:        Currency::Guarani,
    description:     'Monthly Subscription',
);

if ($response->wasSuccess()) {
    // access to change Confirmation data
    $confirmation = $chargeResponse->getConfirmation();
    echo sprintf('Ticket No: %u, Authorization ID: %u',
        $confirmation->ticket_number,
        $confirmation->authorization_number);

    // also access to the security information data
    $securityInformation = $confirmation->getSecurityInformation();
    echo sprintf('Country: %s, Risk Index: %.2F',
        $securityInformation->card_country,
        $securityInformation->risk_index);
}
```

4. **Get the confirmation of a Payment**

Endpoint to get the confirmation of a payment. Example, in case the above charge request stayed as a pending of confirmation payment.

```
use HDSSolutions\Bancard\Bancard;
use HDSSolutions\Bancard\Models\Confirmation;

$confirmationResponse = Bancard::confirmation(
    shop_process_id: $chargeResponse->getRequest()->getShopProcessId(),
);
```

5. **Rollback a Payment**

```
use HDSSolutions\Bancard\Bancard;

$rollbackResponse = Bancard::rollback(
    shop_process_id: $chargeResponse->getRequest()->getShopProcessId(),
);
```

6. **Remove a Registered Card**

```
use HDSSolutions\Bancard\Bancard;
use HDSSolutions\Bancard\Models\Card;

$response = Bancard::card_delete(
    card: $card,  // must be an instance of Card, obtained from Bancard::users_cards()
);
```

### Error Handling

[](#error-handling)

The SDK provides comprehensive error handling for various scenarios:

#### 1. Basic Error Handling

[](#1-basic-error-handling)

```
$response = Bancard::single_buy(/* ... */);

if (! $response->wasSuccess()) {
    foreach ($response->getMessages() as $message) {
        echo sprintf(
            "Error: [%s] %s (Level: %s)\n",
            $message->key,
            $message->description,
            $message->level
        );
    }
}
```

#### 2. Transaction Response Handling

[](#2-transaction-response-handling)

```
$response = Bancard::charge(/* ... */);

if ($response->wasSuccess()) {
    $confirmation = $response->getConfirmation();

    // Access confirmation details
    echo "Response: {$confirmation->response}\n";
    echo "Response Details: {$confirmation->response_details}\n";
    echo "Response Description: {$confirmation->response_description}\n";

    // Access security information
    $security = $confirmation->getSecurityInformation();
    echo "Customer IP: {$security->customer_ip}\n";
    echo "Card Country: {$security->card_country}\n";
    echo "Risk Index: {$security->risk_index}\n";
}
```

#### 3. Debug Information

[](#3-debug-information)

```
if (! $response->wasSuccess()) {
    // Get request details
    $request = $response->getRequest();
    echo "Request Body: {$request->getBody()->getContents()}\n";

    // Get response details
    echo "Response Status: {$response->getStatusCode()}\n";
    echo "Response Body: {$response->getBody()->getContents()}\n";

    // Log for debugging
    error_log(sprintf(
        "Bancard API Error: %s, Status: %d, Body: %s",
        $response->getMessages()[0]->description ?? 'Unknown error',
        $response->getStatusCode(),
        $response->getBody()->getContents()
    ));
}
```

VentasQR Integration
--------------------

[](#ventasqr-integration)

### VentasQR Credentials

[](#ventasqr-credentials)

⚠ **Important**: VentasQR is not scoped by `Bancard::useProduction()`, since your assigned domain will define your testing/production environment.

```
use HDSSolutions\Bancard\Bancard;

Bancard::qr_credentials(
    serviceUrl:     'YOUR_QR_ASSIGNED_DOMAIN',
    publicKey:      'YOUR_QR_PUBLIC_KEY',
    privateKey:     'YOUR_QR_PRIVATE_KEY',
    qrCommerceCode: 1234,
    qrBranchCode:   123,
);
```

### VentasQR Features

[](#ventasqr-features)

- Generate QR codes for payments
- Revert QR payments

### VentasQR Usage Examples

[](#ventasqr-usage-examples)

1. **Generate QR Code**

```
$response = Bancard::qr_generate(
    amount:      $amount,
    description: 'Product Purchase',
);

if ($response->wasSuccess()) {
    // access the generated QR data
    $qrExpress = $qrGenerateResponse->getQRExpress();
    echo sprintf('QR Payment ID: %s, QR Image url: %s, QR Data: %s',
        $qrExpress->hook_alias,
        $qrExpress->url,
        $qrExpress->qr_data);

    // access the list of supported clients
    $supportedClients = $qrGenerateResponse->getSupportedClients();
    foreach ($supportedClients as $supportedClient) {
        echo sprintf('Client name: %s, Client Logo url: %s',
            $supportedClient->name,
            $supportedClient->logo_url);
    }
}
```

2. **Revert QR Payment**

```
$response = Bancard::qr_revert(
    hook_alias: $qrExpress->hook_alias,
);

if ($response->wasSuccess()) {
    echo "Payment successfully reverted\n";
}
```

Advanced Usage
--------------

[](#advanced-usage)

### Request/Response Inspection

[](#requestresponse-inspection)

Access request and response details for debugging:

```
// From response to request
$request = $response->getRequest();
echo "Request Body: " . $request->getBody()->getContents() . "\n";

// From request to response
$response = $request->getResponse();
echo "Response Body: " . $response->getBody()->getContents() . "\n";
```

### Customizable requests

[](#customizable-requests)

If you need, you can create a pending request and change the values on runtime. This applies to all available requests.

```
use HDSSolutions\Bancard\Bancard;
use HDSSolutions\Bancard\Models\Currency;

$singleBuyRequest = Bancard::newSingleBuyRequest(
    shop_process_id: $shop_process_id,
    amount:          $amount,
    description:     'Premium Subscription',
    currency:        Currency::Guarani,
    return_url:      'https://your-domain.com/payment/success-callback-path',
    cancel_url:      'https://your-domain.com/payment/cancel-callback-path',
);
// for example, enable Zimple flag for this request
$singleBuyRequest->enableZimple();
// for Zimple, you need to specify the user's phone number on the additional data property
$singleBuyRequest->setAdditionalData($phone_no);

// after building the request, you can call the execute() method to send the request to Bancard
if (! $singleBuyRequest->execute()) {
    // if failed, you can access the response, and the messages
    $singleBuyRequest->getResponse()->getMessages();
}
```

API Reference
-------------

[](#api-reference)

### vPOS Methods

[](#vpos-methods)

- `Bancard::single_buy()` - Process a one-time payment
- `Bancard::single_buy_zimple()` - Process a Zimple payment
- `Bancard::card_new()` - Register a new card
- `Bancard::users_cards()` - List user's registered cards
- `Bancard::card_delete()` - Remove a registered card
- `Bancard::charge()` - Charge a registered card
- `Bancard::confirmation()` - Check payment status
- `Bancard::preauthorizationConfirm()` - Confirm a pre-authorized payment
- `Bancard::rollback()` - Cancel a pending transaction

### VentasQR Methods

[](#ventasqr-methods)

- `Bancard::qr_generate()` - Generate a QR code for payment
- `Bancard::qr_revert()` - Cancel a QR payment

### Currency Support

[](#currency-support)

The SDK supports multiple currencies through the `Currency` class:

- `Currency::Guarani` - Paraguayan Guarani (PYG)
- `Currency::Dollar` - US Dollar (USD)

For detailed API documentation, visit:

- [Bancard vPOS Documentation](https://www.bancard.com.py/vpos)
- [Bancard VentasQR Documentation](https://comercios.bancard.com.py/productos/ventas-qr)

Contributing
------------

[](#contributing)

Contributions are welcome! If you find any issues or would like to add new features or improvements, please feel free to submit a pull request.

### Contributors

[](#contributors)

- [Hermann D. Schimpf](https://github.com/hschimpf)

### Security Vulnerabilities

[](#security-vulnerabilities)

If you encounter any security-related issues, please feel free to raise a ticket on the issue tracker.

License
-------

[](#license)

This library is open-source software licensed under the [MIT License](LICENSE). Please see the [License File](LICENSE) for more information.

###  Health Score

35

—

LowBetter than 80% of packages

Maintenance41

Moderate activity, may be stable

Popularity23

Limited adoption so far

Community9

Small or concentrated contributor base

Maturity54

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 100% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~171 days

Total

5

Last Release

494d ago

### Community

Maintainers

![](https://www.gravatar.com/avatar/50f96185442e90979dd407a9503e3362a285741fac3e00545bf570235ff7901e?d=identicon)[hschimpf](/maintainers/hschimpf)

---

Top Contributors

[![hschimpf](https://avatars.githubusercontent.com/u/493357?v=4)](https://github.com/hschimpf "hschimpf (68 commits)")

---

Tags

bancardphpqrventasqrvpos

###  Code Quality

TestsPHPUnit

### Embed Badge

![Health badge](/badges/hds-solutions-bancard-sdk/health.svg)

```
[![Health](https://phpackages.com/badges/hds-solutions-bancard-sdk/health.svg)](https://phpackages.com/packages/hds-solutions-bancard-sdk)
```

###  Alternatives

[spatie/crawler

Crawl all internal links found on a website

2.8k16.3M52](/packages/spatie-crawler)[google/cloud

Google Cloud Client Library

1.2k16.2M53](/packages/google-cloud)[google/cloud-core

Google Cloud PHP shared dependency, providing functionality useful to all components.

343121.4M79](/packages/google-cloud-core)[googleads/googleads-php-lib

Google Ad Manager SOAP API Client Library for PHP

67410.3M25](/packages/googleads-googleads-php-lib)[drupal/core

Drupal is an open source content management platform powering millions of websites and applications.

19562.3M1.3k](/packages/drupal-core)[stechstudio/laravel-zipstream

A fast and simple streaming zip file downloader for Laravel.

4633.7M3](/packages/stechstudio-laravel-zipstream)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)