{"id":36374692,"url":"https://github.com/hschimpf/bancard-sdk","last_synced_at":"2026-01-11T14:05:32.477Z","repository":{"id":82922908,"uuid":"601792361","full_name":"hschimpf/bancard-sdk","owner":"hschimpf","description":"Library to implement Bancard vPOS and VentasQR products","archived":false,"fork":false,"pushed_at":"2025-01-10T00:01:25.000Z","size":194,"stargazers_count":7,"open_issues_count":0,"forks_count":2,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-10-04T17:18:23.101Z","etag":null,"topics":["bancard","php","qr","ventasqr","vpos"],"latest_commit_sha":null,"homepage":"https://bancard.com.py/vpos","language":"PHP","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/hschimpf.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2023-02-14T20:39:40.000Z","updated_at":"2025-05-02T18:28:28.000Z","dependencies_parsed_at":null,"dependency_job_id":"3a7c28a8-f397-409c-911f-293e8645ee79","html_url":"https://github.com/hschimpf/bancard-sdk","commit_stats":null,"previous_names":[],"tags_count":4,"template":false,"template_full_name":null,"purl":"pkg:github/hschimpf/bancard-sdk","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hschimpf%2Fbancard-sdk","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hschimpf%2Fbancard-sdk/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hschimpf%2Fbancard-sdk/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hschimpf%2Fbancard-sdk/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/hschimpf","download_url":"https://codeload.github.com/hschimpf/bancard-sdk/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hschimpf%2Fbancard-sdk/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28306985,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-11T11:18:18.743Z","status":"ssl_error","status_checked_at":"2026-01-11T11:07:56.842Z","response_time":60,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["bancard","php","qr","ventasqr","vpos"],"created_at":"2026-01-11T14:05:30.458Z","updated_at":"2026-01-11T14:05:32.470Z","avatar_url":"https://github.com/hschimpf.png","language":"PHP","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Bancard SDK\n\nA 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.\n\n[![Latest stable version](https://img.shields.io/packagist/v/hds-solutions/bancard-sdk?style=flat-square\u0026label=latest\u0026color=0092CB)](https://github.com/hschimpf/bancard-sdk/releases/latest)\n[![License](https://img.shields.io/github/license/hschimpf/bancard-sdk?style=flat-square\u0026color=009664)](https://github.com/hschimpf/bancard-sdk/blob/main/LICENSE)\n[![Total Downloads](https://img.shields.io/packagist/dt/hds-solutions/bancard-sdk?style=flat-square\u0026color=747474)](https://packagist.org/packages/hds-solutions/bancard-sdk)\n[![Monthly Downloads](https://img.shields.io/packagist/dm/hds-solutions/bancard-sdk?style=flat-square\u0026color=747474\u0026label)](https://packagist.org/packages/hds-solutions/bancard-sdk)\n[![Required PHP version](https://img.shields.io/packagist/dependency-v/hds-solutions/bancard-sdk/php?style=flat-square\u0026color=006496\u0026logo=php\u0026logoColor=white)](https://packagist.org/packages/hds-solutions/bancard-sdk)\n\n## Table of Contents\n- [Installation](#installation)\n- [Configuration](#configuration)\n- [vPOS Integration](#vpos-integration)\n  - [Features](#vpos-features)\n  - [Usage Examples](#vpos-usage-examples)\n  - [Error Handling](#error-handling)\n- [VentasQR Integration](#ventasqr-integration)\n  - [Features](#ventasqr-features)\n  - [Usage Examples](#ventasqr-usage-examples)\n- [Advanced Usage](#advanced-usage)\n- [API Reference](#api-reference)\n- [Contributing](#contributing)\n- [License](#license)\n\n## Installation\n\n### Requirements\n- PHP \u003e= 8.0\n\n### Via composer\n```bash\ncomposer require hds-solutions/bancard-sdk\n```\n\n## Configuration\n\n### Setting up Credentials\n\n```php\nuse HDSSolutions\\Bancard\\Bancard;\n\n// Set your vPOS API credentials\nBancard::credentials(\n    publicKey:  'YOUR_PUBLIC_KEY',\n    privateKey: 'YOUR_PRIVATE_KEY',\n);\n```\n\n### Environment Configuration\n\nThe SDK uses the staging environment by default for vPOS. Switch to production when ready:\n\n```php\nuse HDSSolutions\\Bancard\\Bancard;\n\n// Switch to production\nBancard::useProduction();\n\n// Or dynamically based on your application environment\nBancard::useProduction(config('app.env') === 'production');\n```\n\n## vPOS Integration\n\n### vPOS Features\n- Single payments\n- Single payments through Zimple\n- Card management\n- Charge payments to registered cards\n- Pre-authorization\n- Transaction management _(get confirmation and rollback payments)_\n\n### vPOS Usage Examples\n\n#### Single Payment Flow\n\nEndpoint used to generate a process ID to call the Bancard `\u003ciframe\u003e` for a one-time payment.\n\n```php\nuse HDSSolutions\\Bancard\\Bancard;\nuse HDSSolutions\\Bancard\\Models\\Currency;\n\n$response = Bancard::single_buy(\n    shop_process_id: $shop_process_id,\n    amount:          $amount,\n    description:     'Premium Subscription',\n    currency:        Currency::Guarani,\n    return_url:      'https://your-domain.com/payment/success',\n    cancel_url:      'https://your-domain.com/payment/cancel',\n);\n\nif ($singleBuyResponse-\u003ewasSuccess()) {\n    // access the generated process ID to call the Bancard \u003ciframe\u003e\n    $process_id = $singleBuyResponse-\u003egetProcessId();\n}\n\n```\n\n#### Single Payment Flow through Zimple\n\nSame as above, but for `Zimple` payments.\n\n```php\nuse HDSSolutions\\Bancard\\Bancard;\nuse HDSSolutions\\Bancard\\Models\\Currency;\n\n$singleBuyResponse = Bancard::single_buy_zimple(\n    shop_process_id: $shop_process_id,\n    amount:          $amount,\n    description:     'Premium Subscription',\n    currency:        Currency::Guarani,\n    phone_no:        $phone_no, // this field is automatically send on the `additional_data` property of the request\n    return_url:      'https://localhost/your-success-callback-path',\n    cancel_url:      'https://localhost/your-cancelled-callback-path',\n);\n```\n\n#### Card Management\n\n1. **Register a New Card**\n```php\nuse HDSSolutions\\Bancard\\Bancard;\n\n$response = Bancard::card_new(\n    user_id:    $user_id,\n    card_id:    $card_id,\n    phone_no:   '+595991234567',\n    email:      'user@example.com',\n    return_url: 'https://your-domain.com/cards/callback',\n);\n\nif ($response-\u003ewasSuccess()) {\n    // access the generated process ID to call the Bancard \u003ciframe\u003e\n    $processId = $response-\u003egetProcessId();\n}\n```\n\n2. **List User's Cards**\n```php\nuse HDSSolutions\\Bancard\\Bancard;\nuse HDSSolutions\\Bancard\\Models\\Card;\n\n$response = Bancard::users_cards(\n    user_id: $user_id,\n);\n\nif ($response-\u003ewasSuccess()) {\n    foreach ($response-\u003egetCards() as $card) {\n        echo \"Card: {$card-\u003ecard_masked_number}\\n\";\n        echo \"Brand: {$card-\u003ecard_brand}\\n\";\n        echo \"Expiration: {$card-\u003eexpiration_date}\\n\";\n    }\n}\n```\n\n3. **Charge a Registered Card**\n```php\nuse HDSSolutions\\Bancard\\Bancard;\nuse HDSSolutions\\Bancard\\Models\\Card;\nuse HDSSolutions\\Bancard\\Models\\Currency;\nuse HDSSolutions\\Bancard\\Models\\Confirmation;\nuse HDSSolutions\\Bancard\\Models\\SecurityInformation;\n\n$response = Bancard::charge(\n    card:            $card,\n    shop_process_id: $shop_process_id,\n    amount:          $amount,\n    currency:        Currency::Guarani,\n    description:     'Monthly Subscription',\n);\n\nif ($response-\u003ewasSuccess()) {\n    // access to change Confirmation data\n    $confirmation = $chargeResponse-\u003egetConfirmation();\n    echo sprintf('Ticket No: %u, Authorization ID: %u',\n        $confirmation-\u003eticket_number,\n        $confirmation-\u003eauthorization_number);\n    \n    // also access to the security information data\n    $securityInformation = $confirmation-\u003egetSecurityInformation();\n    echo sprintf('Country: %s, Risk Index: %.2F',\n        $securityInformation-\u003ecard_country,\n        $securityInformation-\u003erisk_index);\n}\n```\n\n4. **Get the confirmation of a Payment**\n\nEndpoint to get the confirmation of a payment. Example, in case the above charge request stayed as a pending of confirmation payment.\n\n```php\nuse HDSSolutions\\Bancard\\Bancard;\nuse HDSSolutions\\Bancard\\Models\\Confirmation;\n\n$confirmationResponse = Bancard::confirmation(\n    shop_process_id: $chargeResponse-\u003egetRequest()-\u003egetShopProcessId(),\n);\n```\n\n5. **Rollback a Payment**\n```php\nuse HDSSolutions\\Bancard\\Bancard;\n\n$rollbackResponse = Bancard::rollback(\n    shop_process_id: $chargeResponse-\u003egetRequest()-\u003egetShopProcessId(),\n);\n```\n\n6. **Remove a Registered Card**\n\n```php\nuse HDSSolutions\\Bancard\\Bancard;\nuse HDSSolutions\\Bancard\\Models\\Card;\n\n$response = Bancard::card_delete(\n    card: $card,  // must be an instance of Card, obtained from Bancard::users_cards()\n);\n```\n\n### Error Handling\n\nThe SDK provides comprehensive error handling for various scenarios:\n\n#### 1. Basic Error Handling\n```php\n$response = Bancard::single_buy(/* ... */);\n\nif (! $response-\u003ewasSuccess()) {\n    foreach ($response-\u003egetMessages() as $message) {\n        echo sprintf(\n            \"Error: [%s] %s (Level: %s)\\n\",\n            $message-\u003ekey,\n            $message-\u003edescription,\n            $message-\u003elevel\n        );\n    }\n}\n```\n\n#### 2. Transaction Response Handling\n```php\n$response = Bancard::charge(/* ... */);\n\nif ($response-\u003ewasSuccess()) {\n    $confirmation = $response-\u003egetConfirmation();\n    \n    // Access confirmation details\n    echo \"Response: {$confirmation-\u003eresponse}\\n\";\n    echo \"Response Details: {$confirmation-\u003eresponse_details}\\n\";\n    echo \"Response Description: {$confirmation-\u003eresponse_description}\\n\";\n    \n    // Access security information\n    $security = $confirmation-\u003egetSecurityInformation();\n    echo \"Customer IP: {$security-\u003ecustomer_ip}\\n\";\n    echo \"Card Country: {$security-\u003ecard_country}\\n\";\n    echo \"Risk Index: {$security-\u003erisk_index}\\n\";\n}\n```\n\n#### 3. Debug Information\n```php\nif (! $response-\u003ewasSuccess()) {\n    // Get request details\n    $request = $response-\u003egetRequest();\n    echo \"Request Body: {$request-\u003egetBody()-\u003egetContents()}\\n\";\n    \n    // Get response details\n    echo \"Response Status: {$response-\u003egetStatusCode()}\\n\";\n    echo \"Response Body: {$response-\u003egetBody()-\u003egetContents()}\\n\";\n    \n    // Log for debugging\n    error_log(sprintf(\n        \"Bancard API Error: %s, Status: %d, Body: %s\",\n        $response-\u003egetMessages()[0]-\u003edescription ?? 'Unknown error',\n        $response-\u003egetStatusCode(),\n        $response-\u003egetBody()-\u003egetContents()\n    ));\n}\n```\n\n## VentasQR Integration\n\n### VentasQR Credentials\n⚠ **Important**: VentasQR is not scoped by `Bancard::useProduction()`, since your assigned domain will define your testing/production environment.\n\n```php\nuse HDSSolutions\\Bancard\\Bancard;\n\nBancard::qr_credentials(\n    serviceUrl:     'YOUR_QR_ASSIGNED_DOMAIN',\n    publicKey:      'YOUR_QR_PUBLIC_KEY',\n    privateKey:     'YOUR_QR_PRIVATE_KEY',\n    qrCommerceCode: 1234,\n    qrBranchCode:   123,\n);\n```\n\n### VentasQR Features\n- Generate QR codes for payments\n- Revert QR payments\n\n### VentasQR Usage Examples\n\n1. **Generate QR Code**\n```php\n$response = Bancard::qr_generate(\n    amount:      $amount,\n    description: 'Product Purchase',\n);\n\nif ($response-\u003ewasSuccess()) {\n    // access the generated QR data\n    $qrExpress = $qrGenerateResponse-\u003egetQRExpress();\n    echo sprintf('QR Payment ID: %s, QR Image url: %s, QR Data: %s',\n        $qrExpress-\u003ehook_alias,\n        $qrExpress-\u003eurl,\n        $qrExpress-\u003eqr_data);\n    \n    // access the list of supported clients\n    $supportedClients = $qrGenerateResponse-\u003egetSupportedClients();\n    foreach ($supportedClients as $supportedClient) {\n        echo sprintf('Client name: %s, Client Logo url: %s',\n            $supportedClient-\u003ename,\n            $supportedClient-\u003elogo_url);\n    }\n}\n```\n\n2. **Revert QR Payment**\n```php\n$response = Bancard::qr_revert(\n    hook_alias: $qrExpress-\u003ehook_alias,\n);\n\nif ($response-\u003ewasSuccess()) {\n    echo \"Payment successfully reverted\\n\";\n}\n```\n\n## Advanced Usage\n\n### Request/Response Inspection\n\nAccess request and response details for debugging:\n\n```php\n// From response to request\n$request = $response-\u003egetRequest();\necho \"Request Body: \" . $request-\u003egetBody()-\u003egetContents() . \"\\n\";\n\n// From request to response\n$response = $request-\u003egetResponse();\necho \"Response Body: \" . $response-\u003egetBody()-\u003egetContents() . \"\\n\";\n```\n\n### Customizable requests\nIf you need, you can create a pending request and change the values on runtime. This applies to all available requests.\n```php\nuse HDSSolutions\\Bancard\\Bancard;\nuse HDSSolutions\\Bancard\\Models\\Currency;\n\n$singleBuyRequest = Bancard::newSingleBuyRequest(\n    shop_process_id: $shop_process_id,\n    amount:          $amount,\n    description:     'Premium Subscription',\n    currency:        Currency::Guarani,\n    return_url:      'https://your-domain.com/payment/success-callback-path',\n    cancel_url:      'https://your-domain.com/payment/cancel-callback-path',\n);\n// for example, enable Zimple flag for this request\n$singleBuyRequest-\u003eenableZimple();\n// for Zimple, you need to specify the user's phone number on the additional data property\n$singleBuyRequest-\u003esetAdditionalData($phone_no);\n\n// after building the request, you can call the execute() method to send the request to Bancard\nif (! $singleBuyRequest-\u003eexecute()) {\n    // if failed, you can access the response, and the messages\n    $singleBuyRequest-\u003egetResponse()-\u003egetMessages();\n}\n```\n\n## API Reference\n\n### vPOS Methods\n- `Bancard::single_buy()` - Process a one-time payment\n- `Bancard::single_buy_zimple()` - Process a Zimple payment\n- `Bancard::card_new()` - Register a new card\n- `Bancard::users_cards()` - List user's registered cards\n- `Bancard::card_delete()` - Remove a registered card\n- `Bancard::charge()` - Charge a registered card\n- `Bancard::confirmation()` - Check payment status\n- `Bancard::preauthorizationConfirm()` - Confirm a pre-authorized payment\n- `Bancard::rollback()` - Cancel a pending transaction\n\n### VentasQR Methods\n- `Bancard::qr_generate()` - Generate a QR code for payment\n- `Bancard::qr_revert()` - Cancel a QR payment\n\n### Currency Support\n\nThe SDK supports multiple currencies through the `Currency` class:\n- `Currency::Guarani` - Paraguayan Guarani (PYG)\n- `Currency::Dollar` - US Dollar (USD)\n\nFor detailed API documentation, visit:\n- [Bancard vPOS Documentation](https://www.bancard.com.py/vpos)\n- [Bancard VentasQR Documentation](https://comercios.bancard.com.py/productos/ventas-qr)\n\n## Contributing\nContributions are welcome! If you find any issues or would like to add new features or improvements, please feel free to submit a pull request.\n\n### Contributors\n- [Hermann D. Schimpf](https://github.com/hschimpf)\n\n### Security Vulnerabilities\nIf you encounter any security-related issues, please feel free to raise a ticket on the issue tracker.\n\n## License\nThis library is open-source software licensed under the [MIT License](LICENSE).\nPlease see the [License File](LICENSE) for more information.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhschimpf%2Fbancard-sdk","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fhschimpf%2Fbancard-sdk","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhschimpf%2Fbancard-sdk/lists"}