NAME
WebService::BR::Vindi - Perl low level implementation of the https://vindi.com.br brazilian payment gateway.
SYNOPSIS
use WebService::BR::Vindi;
# Contruct the object
my $vindi = WebService::BR::Vindi->new(
api_key => "You API key",
timeout => 120, # HTTP timeout
debug => 1 );
# Conect to vindi REST API and get the result
# post/get/put/delete methods always returns a perl HASHREF with the resulting data
my $subscription = $vindi->get( 'subscriptions/1234' );
if ( $subscription->{subscription}->{status} eq 'active' ) {
# Do whatever you need
}
# A post method example with error handling
# First parameter is the URL endpoint name - /customer
# Second parameter is the POST DATA - which will be automatically JSON encoded and sent to the gateway
my $customer = $vindi->post(
'customers',
{
"name" => 'Customer's name',
"email" => 'his@email.com',
"registry_code" => '',
"code" => 'XYZ',
}
);
# Wops! Something went wrong!
if ( $payment_profile->{ErrorStatus} ) {
# "ErrorStatus" key try to translate the error to an human readable format whenever possible, or send whatever si possible back.
warn "Something went terribly wrong while creating the customer: ".$customer->{ErrorStatus};
# "error" if the vindi's plain error recieved
warn Data::Dumper::Dumper( $customer->{error} );
# You will probably want to keep this and INSERT in your database
} else {
$customer->{customer}->{id};
}
# A little more elaborated example - create a new payment_profile object
my $payment_profile = $vindi->post(
'payment_profiles',
{ "holder_name" => 'Holder Name',
"card_expiration" => '12/2012',
"card_number" => 'XXXXXXXXXXXXXXXX',
"card_cvv" => 'XXX',
"payment_method_code" => "credit_card",
"customer_id" => $customer->{customer}->{id} # This is the vindi's customer ID we just created before
}
);
# Wops! Something went wrong!
if ( $payment_profile->{ErrorStatus} ) {
warn "Something went terribly wrong while creating your payment profile: ".$payment_profile->{ErrorStatus};
# All fine!
} else {
# Do whatever you need
$payment_profile->{payment_profile};
}DESCRIPTION
This is a straight brindge to the Vindi.com.br payment gateway API.
Note that Vindi has no sandbox/test URL - instead, it uses a separate API KEY for testing. So, it's up to you to specify the right API KEY when you call the methods (test or production).
METHDOS
new
Creates the client object.
- api_key
-
You secret Vindi API key. Required.
- debug
-
Boolean, optional. If true, prints HTTPS request/response information to STDERR.
- timeout
-
Integer, optional, defaults to 120s
get
Make a GET request to Vindi API.
my $customer = $vindi->get( '/customer/123' )- endpoint
-
URI PATH. Required.
*** You don't need the "/v1" prefix.
delete
Make a DELETE request to Vindi API.
my $customer = $vindi->delete( '/customer/123' )- endpoint
-
URI PATH. Required. Example: /customer/123
put
Make a PUT request to Vindi API.
- endpoint
-
URI PATH. Required. No /vi prefix required.
post
Make a POST request to Vindi API. You must specify endpoint as first parameter, and a hashref as the second.
my $customer = $vindi->post( 'customer', { name => '...', ... } )- endpoint
-
URL endpoint. Required. No /v1 required.
- data
-
A hash to be sent with the data. Plese check the examples above or the Vindi API docs.
Error handling
Every request, no mather of what type, return a hashref. If this hashref has a key called ErrorStatus with ant true value in it, an error happened. You can print the ErrorStatus value to the user (this library is able to translate some errors to a reasonable human/end user readable text). Or you can check the Vindi's own error object, which will be available on the "error" key.
my $customer = $vindi->post( 'customer', { name => '...', ... } )
if ( $customer->{ErrorStatus} ) {
print $customer->{ErrorStatus};
print Data::Dumper::Dumper( $customer->{error} );
}- ErrorStatus
-
Human friendly error message (whenever possible).
- error
-
The error hashref as sent by the Vindi API.
SEE ALSO
Please check Vindi's full v1 API docs at http://www.vindi.com.br/ (you will need an API key to access this page).
AUTHOR
Diego de Lima, <diego_de_lima@hotmail.com>
SPECIAL THANKS
This module was kindly made available by the https://modeloinicial.com.br/ team.
COPYRIGHT AND LICENSE
Copyright (C) 2017 by Diego de Lima
This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself, either Perl version 5.10.1 or, at your option, any later version of Perl 5 you may have available.