1 package Business::OnlinePayment::Bambora;
4 use base qw/ Business::OnlinePayment::HTTPS /;
5 use feature 'unicode_strings';
9 use Data::Dumper; $Data::Dumper::Sortkeys = 1;
11 use Unicode::Truncate qw( truncate_egc );
14 use vars qw/ $VERSION $DEBUG /;
19 $Data::Dumper::Sortkeys = 1;
22 =head1 INTERNAL METHODS
26 See L<Business::OnlinePayment/set_defaults>
33 $self->server('api.na.bambora.com');
36 # Create accessors for
53 Dispatch to the appropriate handler based on the given action
57 my %action_dispatch_table = (
58 'normal authorization' => 'submit_normal_authorization',
59 'authorization only' => 'submit_authorization_only',
60 'post authorization' => 'submit_post_authorization',
61 'reverse authorization' => 'submit_reverse_authorization',
62 'void' => 'submit_viod',
63 'credit' => 'submit_credit',
64 'tokenize' => 'submit_tokenize',
65 'recurring authorization' => 'submit_recurring_authorization',
66 'modify recurring authorization' => 'modify_recurring_authorization',
72 my $action = lc $self->{_content}->{action}
73 or croak 'submit() called with no action set';
75 my $method = $action_dispatch_table{$action};
77 $self->submit_action_unsupported()
79 && $self->can($method);
84 =head2 submit_normal_authorization
86 Compliete a payment transaction by with an API POST to B</payments>
88 See L<https://dev.na.bambora.com/docs/references/payment_APIs/v1-0-5>
92 sub submit_normal_authorization {
94 my $content = $self->{_content};
96 # Use epoch time as invoice_number, if none is specified
97 $content->{invoice_number} ||= time();
99 # Clarifying Bambora API and Business::OnlinePayment naming conflict
102 # - order_number: user supplied identifier for the order, displayed on reports
103 # - transaction_id: bambora supplied identifier for the order.
104 # this number must be referenced for future actions like voids,
107 # Business::OnlinePayment
108 # - invoice_number: contains the bambora order number
109 # - order_number: contains the bambora transaction id
112 order_number => $self->truncate( $content->{invoice_number}, 30 ),
113 amount => $content->{amount},
114 billing => $self->jhref_billing_address,
118 if ( $content->{card_number} ) {
119 $post{payment_method} = 'card';
121 # Parse the expiration date into expiry_month and expiry_year
122 $self->set_expiration;
125 number => $self->truncate( $content->{card_number}, 20 ),
126 name => $self->truncate( $content->{owner}, 64 ),
127 expiry_month => sprintf( '%02d', $content->{expiry_month} ),
128 expiry_year => sprintf( '%02d', $content->{expiry_year} ),
129 cvd => $content->{cvv2},
130 recurring_payment => $content->{recurring_payment} ? 1 : 0,
135 die 'unknown/unsupported payment method!';
138 my $action = lc $content->{action};
139 if ( $action eq 'normal authorization' ) {
140 $self->path('/v1/payments');
141 } elsif ( $action eq 'authorization only' ) {
142 $self->path('/v1/payments');
143 if ( ref $post{card} ) {
144 $post{card}->{complete} = 0;
146 } elsif ( $action eq 'post authorization' ) {
148 croak 'post authorization cannot be completed - '.
149 'bambora transaction_id must be set as order_number '.
150 'before using submit()'
151 unless $content->{order_number};
154 sprintf 'v1/payments/%s/completions',
155 $content->{order_number}
158 if ( ref $post{card} ) {
159 $post{card}->{complete} = 1
162 die "unsupported action $action";
165 # Parse %post into a JSON string, to be attached to the request POST body
166 my $post_body = encode_json( \%post );
170 post_body => $post_body,
176 $self->path('/v1/payments');
178 my $response = $self->submit_api_request( $post_body );
180 # Error messages already populated upon failure
181 return unless $self->is_success;
183 # Populate transaction result values
184 $self->message_id( $response->{message_id} );
185 $self->authorization( $response->{auth_code} );
186 $self->order_number( $response->{id} );
187 $self->txn_date( $response->{created} );
188 $self->avs_code( $response->{card}{avs_result} );
189 $self->is_success( 1 );
194 =head2 submit_authorization_only
196 Capture a card authorization, but do not complete transaction
200 sub submit_authorization_only {
203 $self->submit_normal_authorization;
205 my $response = $self->response_decoded;
211 && $response->{type} != 'PA'
214 # Bambora API uses nearly identical API calls for normal
215 # card transactions and pre-authorization. Sanity check
216 # that response reported a pre-authorization code
217 die "Expected API Respose type=PA, but type=$response->{type}! ".
218 "Pre-Authorization attempt may have charged card!";
222 =head2 submit_post_authorization
224 Complete a card pre-authorization
228 sub submit_post_authorization {
229 shift->submit_normal_authorization;
232 =head2 submit_reverse_authorization
234 Reverse a pre-authorization
238 sub submit_reverse_authorization {
250 my $content = $self->{_content};
252 for my $f (qw/ order_number invoice_number amount/) {
253 unless ( $content->{$f} ) {
254 $self->error_message("Cannot process void - missing required content $f");
255 warn $self->error_message if $DEBUG;
257 return $self->is_success(0);
262 order_number => $self->truncate( $content->{invoice_number}, 30 ),
263 amount => $content->{amount},
265 my $post_body = encode_json( \%post );
270 post_body => $post_body,
273 $self->path( sprintf '/v1/payments/%s/void', $content->{order_number} );
275 my $response = $self->submit_api_request( $post_body );
279 =head2 submit_api_request json_string
281 Make the appropriate API request with the given JSON string
285 sub submit_api_request {
287 my $post_body = shift
288 or die 'submit_api_request() requires a json_string parameter';
290 my ( $response_body, $response_code, %response_headers ) = $self->https_post(
292 headers => { $self->authorization_header },
293 'Content-Type' => 'application/json',
297 $self->server_response( $response_body );
302 eval{ $response = decode_json( $response_body ) };
306 response_body => $response_body,
307 response => $response,
308 response_code => $response_code,
309 # response_headers => \%response_headers,
313 # API should always return a JSON response, likely network problem
314 if ( $@ || !$response ) {
315 $self->error_message( $response_body || 'connection error' );
316 $self->is_success( 0 );
320 $self->response_decoded( $response );
322 # Response returned an error
323 if ( $response->{code} && $response->{code} != 1 ) {
324 $self->is_success( 0 );
325 $self->result_code( $response->{code} );
327 return $self->error_message(
335 # Return the decoded json of the response back to handler
336 $self->is_success( 1 );
341 =head2 submit_action_unsupported
343 Croak with the error message Action $action unsupported
347 sub submit_action_unsupported {
348 croak sprintf 'Action %s unsupported', shift->action
351 =head2 authorization_header
353 Bambora POST requests authenticate via a HTTP header of the format:
354 Authorization: Passcode Base64Encoded(merchant_id:passcode)
356 Returns a hash representing the authorization header derived from
357 the merchant id (login) and API passcode (password)
361 sub authorization_header {
363 my $content = $self->{_content};
365 my %authorization_header = (
366 Authorization => 'Passcode ' . MIME::Base64::encode_base64(
367 join( ':', $content->{login}, $content->{password} )
372 warn Dumper({ authorization_header => \%authorization_header })."\n";
375 %authorization_header;
378 =head2 jhref_billing_address
380 Return a hashref for inclusion into a json object
381 representing the RequestBillingAddress for the API
385 sub jhref_billing_address {
390 $self->set_phone_number;
392 my $content = $self->{_content};
395 name => $self->truncate( $content->{name}, 64 ),
396 address_line1 => $self->truncate( $content->{address}, 64 ),
397 city => $self->truncate( $content->{city}, 64 ),
398 province => $self->truncate( $content->{province}, 2 ),
399 country => $self->truncate( $content->{country}, 2 ),
400 postal_code => $self->truncate( $content->{zip}, 16 ),
401 phone_number => $self->truncate( $content->{phone_number}, 20 ),
402 email_address => $self->truncate( $content->{email}, 64 ),
408 Country is expected to be set as an ISO-3166-1 2-letter country code
410 Sets string to upper case.
412 Dies unless country is a two-letter string.
414 In the future, could be extended to convert country names to their respective
417 See: L<https://en.wikipedia.org/wiki/ISO_3166-1>
423 my $content = $self->{_content};
424 my $country = uc $content->{country};
426 if ( $country !~ /^[A-Z]{2}$/ ) {
427 croak sprintf 'country is not a 2 character string (%s)',
431 $content->{country} = $country;
434 =head2 set_expiration_month_year
436 Split standard expiration field, which may be in the format
437 MM/YY or MMYY, into separate expiry_month and expiry_year fields
439 Will die if values are not numeric
445 my $content = $self->{_content};
446 my $expiration = $content->{expiration};
450 ? split( /\//, $expiration )
451 : unpack( 'A2 A2', $expiration )
454 croak 'card expiration must be in format MM/YY'
455 if $mm =~ /\D/ || $yy =~ /\D/;
458 $content->{expiry_month} = sprintf( '%02d', $mm ),
459 $content->{expiry_year} = sprintf ('%02d', $yy ),
463 =head2 set_payment_method
465 Set payment_method value to one of the following strings
478 sub set_payment_method {
479 # todo - determine correct payment method
480 warn "set_payment_method() STUB FUNCTION ALWAYS RETURNS card!\n";
481 shift->{_content}->{payment_method} = 'card';
484 =head2 set_phone_number
488 sub set_phone_number {
490 my $content = $self->{_content};
492 my $phone = $content->{phone}
493 or return $content->{phone_number} = undef;
496 $content->{phone_number} = $phone;
501 Outside the US/Canada, API expect province set to the string "--",
502 otherwise to be a 2 character string
508 my $content = $self->{_content};
509 my $country = uc $content->{country};
511 return $content->{province} = '--'
513 && ( $country eq 'US' || $country eq 'CA' );
515 $content->{province} = uc $content->{state};
518 =head2 truncate string, bytes
520 When given a string, truncate to given string length in a unicode safe way
525 my ( $self, $string, $bytes ) = @_;
527 # truncate_egc dies when asked to truncate undef
528 return $string unless $string;
530 truncate_egc( "$string", $bytes, '' );