BatchPayment/Item.pm

   1 package Business::BatchPayment::Item;
   2
   3 use strict;
   4 use Moose;
   5 use Moose::Util::TypeConstraints;
   6 use MooseX::UndefTolerant;
   7 use DateTime;
   8
   9 =head1 NAME
  10
  11 Business::BatchPayment::Item
  12
  13 =head1 DESCRIPTION
  14
  15 A Business::BatchPayment::Item represents a single payment request or
  16 reply (approval or rejection).  When submitting a batch, the merchant
  17 system constructs B::BP::Item objects for each attempted payment in
  18 the batch.  Results downloaded from the gateway are returned as a
  19 list of Items with the 'approved' field set to a true or false value.
  20
  21 =head1 REQUIRED ATTRIBUTES
  22
  23 =over 4
  24
  25 =item action
  26
  27 "payment" or "credit".  Most processors support only "payment".
  28 "payment" is defined as "money transfer FROM the account identified in the
  29 Item TO the account identified by the Processor object's login settings."
  30 "credit" is the other direction.
  31
  32 =cut
  33
  34 enum 'Action' => qw(payment credit);
  35 coerce 'Action', from 'Str', via { lc $_ };
  36 has action => (
  37   is  => 'rw',
  38   isa => 'Action',
  39   default => 'payment',
  40   required => 1,
  41   coerce => 1,
  42 );
  43
  44 =item payment_type
  45
  46 "CC" or "ECHECK".  Most processors will only support one or the other,
  47 and if set on the Processor object, this is not required.
  48
  49 =cut
  50
  51 # are we okay with these names?
  52 enum 'PaymentType' => qw( CC ECHECK );
  53 has payment_type => ( is  => 'rw', isa => 'PaymentType' );
  54
  55 =item amount
  56
  57 the amount, as a decimal number.  Required only in request
  58 items.
  59
  60 =cut
  61
  62 # perhaps we should apply roles that distinguish request and reply items?
  63 # they have different required fields.
  64 has amount => (
  65   is  => 'rw',
  66   isa => 'Num',
  67 );
  68
  69 =item tid
  70
  71 transaction identifier.  Requests must provide this.  It's a token of
  72 some kind to be passed to the gateway and used to identify the reply.
  73 For now it's required to be an integer.  An invoice number would be
  74 a good choice.
  75
  76 =cut
  77
  78 has tid => ( is  => 'rw', isa => 'Int' );
  79
  80 =back
  81
  82 =head1 OPTIONAL ATTRIBUTES
  83
  84 =head2 Customer Information
  85
  86 =over 4
  87
  88 =item customer_id
  89
  90 A customer number or other identifier, for the merchant's use.
  91
  92 =item first_name
  93
  94 First name.
  95
  96 =item last_name
  97
  98 Last name.
  99
 100 =item company
 101
 102 Company name.
 103
 104 =item address, address2, city, state, country, zip
 105
 106 Billing address fields.  Credit card processors may use these (especially
 107 zip) for authentication.
 108
 109 =cut
 110
 111 has [ qw(
 112   customer_id
 113   first_name
 114   last_name
 115   company
 116   address
 117   address2
 118   city
 119   state
 120   country
 121   zip
 122 ) ] => ( is => 'rw', isa => 'Str', default => '' );
 123
 124 =back
 125
 126 =head2 Transaction Information
 127
 128 =over 4
 129
 130 =item process_date
 131
 132 The date requested for processing.
 133
 134 =item invoice_number
 135
 136 An invoice number, for your use.
 137
 138 =cut
 139
 140 class_type 'DateTime';
 141 coerce 'DateTime', from 'Int', via { DateTime->from_epoch($_) };
 142 has process_date    => ( is => 'rw', isa => 'DateTime', coerce => 1 );
 143
 144 has invoice_number  => ( is => 'rw', isa => 'Str' );
 145
 146 =back
 147
 148 =head2 Bank Transfer / ACH / EFT
 149
 150 =over 4
 151
 152 =item account_number
 153
 154 Bank account number.
 155
 156 =item routing_code
 157
 158 Bank's routing code.
 159
 160 =item account_type
 161
 162 Can be 'personal checking', 'personal savings', 'business checking',
 163 or 'business savings'.
 164
 165 =cut
 166
 167 enum 'Account_Type' => [
 168   'personal checking',
 169   'personal savings',
 170   'business checking',
 171   'business savings',
 172 ];
 173 coerce 'Account_Type', from 'Str', via { lc $_ };
 174
 175 has account_number  => ( is => 'rw', isa => 'Str' );
 176 has routing_code    => ( is => 'rw', isa => 'Str' );
 177 has account_type    => ( is => 'rw', isa => 'Account_Type', coerce => 1 );
 178
 179 =back
 180
 181 =head2 Credit Card
 182
 183 =over 4
 184
 185 =item card_number
 186
 187 Credit card number.
 188
 189 =item expiration
 190
 191 Credit card expiration, MMYY format.
 192
 193 =cut
 194
 195 has card_number     => ( is => 'rw', isa => 'Str' );
 196 has expiration      => ( is => 'rw', isa => 'Str' );
 197
 198 =back
 199
 200 =head2 Tokenized Payment
 201
 202 =over 4
 203
 204 =item pay_by_token
 205
 206 If your gateway supports it, this may be
 207 provided instead of card_number/account_number.  See also
 208 C<assigned_token> below.
 209
 210 =cut
 211
 212 has pay_by_token    => ( is => 'rw', isa => 'Str' );
 213
 214 =back
 215
 216 =head1 REPLY ATTRIBUTES
 217
 218 =over 4
 219
 220 =item approved
 221
 222 Boolean field for whether the item was approved.  This
 223 will always be set on replies.
 224
 225 =item payment_date
 226
 227 The date the payment was processed, as a DateTime
 228 object.
 229
 230 =item order_number
 231
 232 The transaction identifier returned by the gateway
 233 (not to be confused with 'tid', which is a transaction identifier assigned
 234 by the merchant system).  This is usually the identifier for performing
 235 other operations on the transaction, like voiding or refunding it.
 236
 237 =item authorization
 238
 239 The authorization code, probably only meaningful for credit cards.
 240 Should be undef (or not present) if the transaction wasn't approved.
 241
 242 =item check_number
 243
 244 The check number, probably only meaningful if this transaction was
 245 processed from a paper check.
 246
 247 =item assigned_token
 248
 249 In tokenized systems which store the customer's account number or
 250 credit card for future transactions, this is the token assigned to
 251 identify that account.  Pass it as 'pay_by_token' to use that payment
 252 account again.
 253
 254 =item error_message
 255
 256 The message returned by the gateway.  This may contain a value even
 257 if the payment was successful (use C<approved> to determine that.)
 258
 259 =back
 260
 261 =cut
 262
 263 has approved        => ( is => 'rw', isa => 'Maybe[Bool]' );
 264
 265 has payment_date    => ( is => 'rw', isa => 'DateTime' );
 266
 267 has [qw(
 268   authorization
 269   error_message
 270   order_number
 271   assigned_token
 272 )] => ( is => 'rw', isa => 'Str');
 273
 274 has check_number => ( is => 'rw', isa => 'Int' );
 275
 276 __PACKAGE__->meta->make_immutable;
 277
 278 1;