hds-solutions/bancard-sdk

Bancard SDK library

v1.1.3 2025-01-09 23:05 UTC

Requires

• php: >=8.0
• guzzlehttp/guzzle: ^7.5
• guzzlehttp/psr7: ^2.4

Requires (Dev)

• phpunit/phpunit: ^9.5
• vlucas/phpdotenv: ^5.5

GPL-3.0

• Hermann D. Schimpf

README

A comprehensive PHP SDK for integrating Bancard vPOS and Bancard VentasQR payment solutions into your applications.

Table of Contents

• Installation
• Configuration
• vPOS Integration
  • Features
  • Usage Examples
  • Error Handling
• VentasQR Integration
  • Features
  • Usage Examples
• Advanced Usage
• API Reference
• Contributing
• License

Installation

Requirements

• PHP >= 8.0

Via composer

composer require hds-solutions/bancard-sdk

Configuration

Setting up Credentials

use HDSSolutions\Bancard\Bancard;

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

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 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

Single Payment Flow

Endpoint used to generate a process ID to call the Bancard <iframe> 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 <iframe>
    $process_id = $singleBuyResponse->getProcessId();
}

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

1. Register a New Card

use HDSSolutions\Bancard\Bancard;

$response = Bancard::card_new(
    user_id:    $user_id,
    card_id:    $card_id,
    phone_no:   '[phone]',
    email:      '[e-mail]',
    return_url: 'https://your-domain.com/cards/callback',
);

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

1. 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";
    }
}

1. 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);
}

1. 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(),
);

1. Rollback a Payment

use HDSSolutions\Bancard\Bancard;

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

1. 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

The SDK provides comprehensive error handling for various scenarios:

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

$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

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 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

• Generate QR codes for payments
• Revert QR payments

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);
    }
}

1. Revert QR Payment

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

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

Advanced Usage

Request/Response 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

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

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

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

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
• Bancard VentasQR Documentation

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

• Hermann D. Schimpf

Security Vulnerabilities

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

License

This library is open-source software licensed under the MIT License. Please see the License File for more information.