PHP Classes

PHP Instapago: Process payments with the Instapago API

Recommend this page to a friend!
  Info   View files Documentation   View files View files (28)   DownloadInstall with Composer Download .zip   Reputation   Support forum   Blog    
Last Updated Ratings Unique User Downloads Download Rankings
2023-05-30 (9 months ago) RSS 2.0 feedNot enough user ratingsTotal: 123 All time: 9,438 This week: 325Up
Version License PHP version Categories
php-instapago 3.0.8MIT/X Consortium ...5.6PHP 5, E-Commerce, Web services
Description 

Author

This class can process payments with the Instapago API.

It can send HTTP requests to the Instapago API Web server to process several types of payment operations.

Currently it can submit a payment request, process pre-authorized payments, cancel a payment, and get information about a payment.

The code comments are in Spanish.

Picture of ángel cruz
  Performance   Level  
Name: ángel cruz <contact>
Classes: 4 packages by
Country: Uruguay Uruguay
Age: 36
All time rank: 39197 in Uruguay Uruguay
Week rank: 550 Up1 in Uruguay Uruguay Up

Documentation

Php Instapago <p align="center"> Documentación de la librería <b>Instapago</b> </p>

Table of Contents

Información General

Credenciales de Pruebas

* keyId = 74D4A278-C3F8-4D7A-9894-FA0571D7E023
* publicKeyId = e9a5893e047b645fed12c82db877e05a

> Importante: Debes solicitar las llaves públicas y privadas (publicKeyId y keyId) a Instapago. Aquí puedes encontrar mayor información.

Parámetros _requeridos_ para crear un pago

  • `card_holder`: Nombre del Tarjeta habiente.
  • `card_holder_id`: Cédula del Tarjeta Habiente,
  • `card_number`: Número de la tarjeta de crédito, 16 dígitos sin separadores.
  • `cvc`: Código de validación de la Tarjeta de crédito.
  • `expiration_date`: Fecha de Vencimiento de la tarjeta. Formato MM/YYYY. Por Ejemplo: 10/2015.
  • `amount`: Monto a Debitar, formato: `0.00` (punto como separador decimal, sin separador de miles).
  • `description`: Texto con la descripción de la operación.
  • `ip`: Dirección IP del cliente.

De ahora en más usaremos $paymentData para referirnos a el arreglo con los parámetros antes mencionados.

$paymentData = [
  'amount' => '200',
  'description' => 'test',
  'card_holder' => 'jon doe',
  'card_holder_id' => '11111111',
  'card_number' => '4111111111111111',
  'cvc' => '123',
  'expiration' => '12/2020',
  'ip' => '127.0.0.1',
];

Retornos

Todos los métodos del api devuelven un arreglo asociativo con el siguiente esquema:

  • `code`: (numeric) Codigo de respuesta de Instapago.
  • `msg_banco`: (string) Mensaje del banco respecto a la transacción.
  • `voucher`: (string) Voucher (muy parecido al ticket que emite el POS en Venezuela) en html.
  • `id_pago`: (string) Identificador del pago en la plataforma de Instapago.
  • `reference`: (numeric) Referencia del pago en la red bancaria.
  • `original_response`: (array) Respuesta original de la plataforma de instapago.

Manejo de errores

La excepción base de la librería es \Instapago\Exceptions\InstapagoException y reporta errores generales con instapago, y de ella se derivan 5 excepciones de la siguiente manera.

  • `Instapago\Exceptions\AuthException`: es lanzada cuando Instapago retorna error en las credenciales.
  • `Instapago\Exceptions\BankRejectException`: es lanzada cuando un pago es rechazado por el banco.
  • `Instapago\Exceptions\InvalidInputException`: es lanzada cuando instapago rechaza la entrada de datos.
  • `Instapago\Exceptions\TimeoutException`: es lanzada cuando es imposible conectarse al api de Instapago y expira el tiempo de carga.
  • `Instapago\Exceptions\ValidationException`: es lanzada cuando la entrada de datos es inválida. (antes de ser enviada a Instapago).

Códigos de respuesta

Para todas las transacciones realizadas bajo el API de Instapago, los códigos HTTP de respuestas corresponden a los siguientes estados:

  • 
    
  • 
    
  • 
    

> Importante: Si recibe un código de respuesta diferente a los antes descritos deben ser tomados como errores de protocolo HTTP.

Tarjetas de prueba

Para realizar las pruebas, se provee de los siguientes datos para comprobar la integracio?n:

  • Tarjetas Aprobadas:

Pueden indicar cualquier valor para Ce?dula o RIF, Fecha de Vencimiento y CVC:

  • Visa: `4111111111111111`
  • American Express: `378282246310005`
  • MasterCard: `5105105105105100`
  • Sambil: `8244001100110011`
  • Rattan: `8244021100110011`
  • Locatel: `8244041100110011`

API

Instanciación

$api = new \Instapago\Api('<keyId>','<publicKeyId>');

Crear un Pago Directo

Efectúa un pago directo con tarjeta de crédito, los pagos directos son inmediatamente debitados del cliente y entran en el proceso bancario necesario para acreditar al beneficiario.

try{
  $api = new Api('<keyId>','<publicKeyId>');

  $respuesta = $api->directPayment($paymentData);
  // hacer algo con $respuesta
}catch(\Instapago\Exceptions\InstapagoException $e){

  echo "Ocurrió un problema procesando el pago.";
  // manejar el error 
}

Reservar un Pago

Efectúa una reserva o retención de pago en la tarjeta de crédito del cliente, la reserva diferirá los fondos por un tiempo (3 días máximo segun fuentes extraoficiales), en el plazo en el que los fondos se encuentren diferidos, ni el beneficiario ni el cliente poseen el dinero. El dinero será tramitado al beneficiario una vez completado el pago, o de lo contrario será acreditado al cliente de vuelta si no se completa durante el plazo o si se cancela el pago.

try{
  $api = new Api('<keyId>','<publicKeyId>');

  $respuesta = $api->reservePayment($paymentData);
  // hacer algo con $respuesta
}catch(\Instapago\Exceptions\InstapagoException $e){

  echo "Ocurrió un problema procesando el pago.";
  // manejar el error 
}

Completar Pago

Éste método permite cobrar fondos previamente retenidos.

  • `id`: Identificador único del pago.
  • `amount`: Monto por el cual se desea procesar el pago final.
try{
  $api = new Api('<keyId>','<publicKeyId>');

  $respuesta = $api-continuePayment([
    'id' => 'af614bca-0e2b-4232-bc8c-dbedbdf73b48',
    'amount' => '200.00'
  ]);

}catch(\Instapago\Exceptions\InstapagoException $e){
  // manejar errores
}

Información de un Pago

Consulta información sobre un pago previamente generado.

try{
  $api = new Api('<keyId>','<publicKeyId>');

  $idPago = 'af614bca-0e2b-4232-bc8c-dbedbdf73b48';
  
  $respuesta = $api->query($idPago);

}catch(\Instapago\Exceptions\InstapagoException $e){
  // manejar errores
}

Devuelve la misma respuesta que los métodos de crear pagos.

Anular Pago

Este método permite cancelar un pago, haya sido directo o retenido.

try{
  $api = new Api('<keyId>','<publicKeyId>');

  $idPago = 'af614bca-0e2b-4232-bc8c-dbedbdf73b48';

  $info = $api->cancel($idPago);
  
}catch(\Instapago\Exceptions\InstapagoException $e){
  // manejar errores
}

Devuelve la misma respuesta que los métodos de crear pagos.


Details

<p align="center"> <img src="help/hYNsH6B.png">

</p> <p align="center">

Librería Instapago para PHP

</p> <p align="center">

<sup style="color: #d0d0d0;"><b>NOTA</b> Los logos son propiedad de Instapago y Banesco, respectivamente.</sup>

</p>

Latest Version on Packagist GitHub Workflow Status Total Downloads

instalación

Primero, composer

Luego:

$ composer require instapago/instapago
$ composer dumpautoload -o // opcional

como usar

>NOTA: Tomar en cuenta que esta nueva versión fue probada usando php8.X, no aseguro que funcione en algo menor a eso, en teoría debería pero no estoy seguro.

<?php

require 'vendor/autoload.php';

use \Instapago\Instapago\Api;
use \Instapago\Instapago\Exceptions\{
	InstapagoException,
	AuthException,
	BankRejectException,
	InvalidInputException,
	TimeoutException,
	ValidationException,
	GenericException,
};


$paymentData = [
  'amount' => '200',
  'description' => 'test',
  'card_holder' => 'jon doe',
  'card_holder_id' => '11111111',
  'card_number' => '4111111111111111',
  'cvc' => '123',
  'expiration' => '12/2020',
  'ip' => '127.0.0.1',
];

try{

  $api = new Api('<keyId>','<publicKeyId>');

  $respuesta = $api->directPayment($paymentData);
  // hacer algo con $respuesta
}catch(InstapagoException $e){

  echo $e->getMessage(); // manejar el error

}catch(AuthException $e){

  echo $e->getMessage(); // manejar el error

}catch(BankRejectException $e){

  echo $e->getMessage(); // manejar el error

}catch(InvalidInputException $e){

  echo $e->getMessage(); // manejar el error

}catch(TimeoutException $e){

  echo $e->getMessage(); // manejar el error

}catch(ValidationException $e){

  echo $e->getMessage(); // manejar el error

}catch(GenericException $e){

  echo $e->getMessage(); // manejar el error

}

Podemos revisar rápidamente si todo funciona correctamente escribiendo:

$ php -S localhost:8000

tests

composer test

Changelog

Please see CHANGELOG for more information on what has changed recently.

Contributing

Please see CONTRIBUTING for details.

Security Vulnerabilities

Please review our security policy on how to report security vulnerabilities.

Credits

License

The MIT License (MIT). Please see License File for more information.


  Files folder image Files  
File Role Description
Files folder image.github (2 files, 2 directories)
Files folder imagehelp (2 files)
Files folder imagesrc (2 files, 1 directory)
Files folder imagetests (2 files)
Accessible without login Plain text file .editorconfig Data Auxiliary data
Accessible without login Plain text file .php-cs-fixer.dist.php Example Example script
Accessible without login Plain text file CHANGELOG.md Data Auxiliary data
Accessible without login Plain text file composer.json Data Auxiliary data
Accessible without login Plain text file LICENSE.md Lic. License text
Accessible without login Plain text file README.md Doc. Example script

  Files folder image Files  /  .github  
File Role Description
Files folder imageISSUE_TEMPLATE (2 files)
Files folder imageworkflows (5 files)
  Accessible without login Plain text file dependabot.yml Data Auxiliary data
  Accessible without login Plain text file FUNDING.yml Data Auxiliary data

  Files folder image Files  /  .github  /  ISSUE_TEMPLATE  
File Role Description
  Accessible without login Plain text file bug.yml Data Auxiliary data
  Accessible without login Plain text file config.yml Data Auxiliary data

  Files folder image Files  /  .github  /  workflows  
File Role Description
  Accessible without login Plain text file dependabot-auto-merge.yml Data Auxiliary data
  Accessible without login Plain text file fix-php-code-style-issues-cs-fixer.yml Data Auxiliary data
  Accessible without login Plain text file fix-php-code-style-issues-pint.yml Data Auxiliary data
  Accessible without login Plain text file run-tests-pest.yml Data Auxiliary data
  Accessible without login Plain text file update-changelog.yml Data Auxiliary data

  Files folder image Files  /  help  
File Role Description
  Accessible without login Plain text file DOCUMENTACION.md Doc. Documentation
  Accessible without login Image file hYNsH6B.png Icon Icon image

  Files folder image Files  /  src  
File Role Description
Files folder imageExceptions (7 files)
  Plain text file Api.php Class Class source
  Plain text file Validator.php Class Class source

  Files folder image Files  /  src  /  Exceptions  
File Role Description
  Plain text file AuthException.php Class Class source
  Plain text file BankRejectException.php Class Class source
  Plain text file GenericException.php Class Class source
  Plain text file InstapagoException.php Class Class source
  Plain text file InvalidInputException.php Class Class source
  Plain text file TimeoutException.php Class Class source
  Plain text file ValidationException.php Class Class source

  Files folder image Files  /  tests  
File Role Description
  Plain text file ApiInstapagoTest.php Class Class source
  Accessible without login Plain text file Pest.php Aux. Auxiliary script

 Version Control Unique User Downloads Download Rankings  
 100%
Total:123
This week:0
All time:9,438
This week:325Up