* Copyright © 2009-2010, Bruce-Robert Pocock *
** Based upon public domain sample code provided by Authorize.net *
** This program is free software; you can redistribute it and/or modify * it under the terms of the GNU General Public License as published by * the Free Software Foundation, either version 3 of the License, or (at * your option) any later version. *
** This program is distributed in the hope that it will be useful, but * WITHOUT ANY WARRANTY; without even the implied warranty of * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU * General Public License for more details. *
*
* You should have received a copy of the GNU General Public License
* along with this program. If not, see
* The collection of additional annotations for record-keeping or * other purposes. These are things not used by the system, but * which are tracked in case they're useful for human review, * auditing, etc. *
** Annotations are keyed off dotted domain sequences in the same * general fashion as Java class names, etc. *
*/ private HashMap* The time at which we first tried to post this payment. If a * temporary problem was encountered, we can hold on to it (in core) * and retry for a while, until a (configured) timeout has been * reached. *
** This field is not persistent. *
*/ private transient Date firstTried; /** * The time at which we last tried to re-submit a pending * transaction */ private transient long lastTried; /** * The order code is an unique string for this order among all * orders placed through a specific source (payment gateway, * generally) */ private String order_code = ""; /** * The order's source code is an identifier which maps to the * payment gateway class, but is user-visible as a part of the total * payment identifier (source, code, and sequence number) */ private String order_source = ""; /** * The amount actually paid with this payment. This should generally * be the same as the price (I can't think of a valid * counter-example!) */ private BigDecimal paid = BigDecimal.ZERO; /** * The identification of the payer */ private String payer; /** * WRITEME */ private String paymentFor = "NIL"; /** * Through what payment gateway was this payment processed? */ private PaymentGatewayReal paymentGateway; /** * The price paid in this payment */ private BigDecimal price; /** * The reason for the failure (if it failed), or the authorization * code for the success (if it succeeded) */ private String resultReason; /** * The sequence number indicates a series of payments that are * related to the same event; this is (always, right now, but) * typically a subscription recurring every month. */ private int sequence = 0; /** * The moment in time at which, per our accounting, this * payment took place. Note that the user might see a different time * on his or her wall clock or credit card statements, &c. There is * a degree of ambiguity about when various people consider the * transaction to have been completed. Per our purposes, this is * that moment. */ private Timestamp stamp; /** * Was the payment a success? We keep records of failed payments, * too, so it's important to ask that question. */ private boolean success = false; /** * Was this a test transaction, submitted by the system? It's * possible. If this istrue, we shouldn't give out
* anything because of it.
*/
private boolean testMode = false;
/**
* The transaction code returned by the payment gateway
*/
private BigDecimal transactionCode = null;
/**
* If this payment was made for an enrolment subscription (right now
* (TODO) they all are), then this stores the pointer to the
* UserEnrolment record in question.
*/
private UserEnrolment userEnrolment = null;
/**
* True, if the payment has been reconciled or verified.
*/
private boolean verified;
/**
* Handle Silent Post data returned by Authorize.Net.
*
* @param gatewayClass The class responsible for this payment;
* should always be AuthorizeNetGateway for now. Provides
* an easy hook to make sure we're in the right place,
* not processing e.g. PayPal data here.
* @param authorizeNetData The key:value pairs of the data from
* Authorize.Net
*/
public Payment (final Class * Note: Credentials for payment are not * saved to JSON or database. As such, they only persist as long as * they're held in-core. *
** For this reason, we need to hold on to pending payments' * references to avoid potential GC. We cannot * re-instantiate a non-completed payment from the database. *
** This is an intentional security precaution. *
* * @return the credentials used to make the payment. */ public PaymentCredential getCredentials () { return credentials; } /** * Get the currency with which this payment was/will be made * ** As with many things, this is still hardcoded as USD. *
* * @return the currency used to make this payment */ public Currency getCurrency () { return Currency.get_USD (); } /** * @return the expiryMonth */ public synchronized int getExpiryMonth () { // default getter (brpocock, Sep 11, 2009) return expiryMonth; } /** * @return the expiryYear */ public synchronized int getExpiryYear () { // default getter (brpocock, Sep 11, 2009) return expiryYear; } /** * @return The transaction code provided by the payment gateway */ public synchronized BigDecimal getGatewayTransactionCode () { return transactionCode; } /** * @return the paid */ public BigDecimal getPaid () { // default getter (brpocock, Jul 14, 2009) return paid; } /** * @return get the name or other identification provided by the * gateway of the payer. (Non-confidential but potentially * personally identifiable.) */ public synchronized String getPayer () { return payer; } /** * Use {@link #getPaymentFor()} instead * * @return the payment_for */ @Deprecated public String getPayment_for () { return paymentFor; } /** * @return the payment_for */ public String getPaymentFor () { return paymentFor; } /** * @return The payment gateway used to make this payment */ public synchronized PaymentGateway getPaymentGateway () { return (PaymentGateway) paymentGateway; } /** * @return the price */ public BigDecimal getPrice () { // default getter (brpocock, Jul 15, 2009) return price; } /** * @return The prior payment in this subscription or other recurring * payment arrangement * @throws NotFoundException if there wasn't a prior sequence * payment. */ public synchronized Payment getPriorPayment () throws NotFoundException { if (getSequence () == 0) throw new NotFoundException ("First payment in sequence"); return new Payment (order_source, order_code, getSequence () - 1); } /** * @return the failedReason */ public String getResultReason () { // default getter (brpocock, Jul 14, 2009) return resultReason; } /** ** If this payment is pending, and we're holding credentials in * core, we need to figure out how long before we try again. In the * spirit of exponential back-off, we'll try every 1 minute for the * first 10 minutes, then back off to every 5 minutes for the next * 50 minutes, after which we'll go to every 15 minutes until it's * been 12 hours, after which time, we'll try every hour until the * payment record is dropped. *
** Note that we need to keep a hard reference to this Payment in the * timer routine handling re-submissions, because if the Payment * record is purged from the cache, we lose the credentials. This is * intentional: we don't want to keep credentials lying around, * ever. *
* * @return the date at which we'll next try to complete this payment * @throws AlreadyUsedException if the payment can't be retried * @throws DataException if there are no payment credentials * available for retrying */ public Date getRetryTime () throws AlreadyUsedException, DataException { // Can we retry at all? if (stamp != null) throw new AlreadyUsedException ("Payment completed", stamp); if (firstTried == null) throw new AlreadyUsedException ("Not a retry:able payment", new Date (System.currentTimeMillis ())); if (credentials == null) throw new DataException ("No credentials available"); if (lastTried < firstTried.getTime ()) { lastTried = firstTried.getTime (); } // How long have we been trying? (in milliseconds) final long duration = System.currentTimeMillis () - firstTried.getTime (); if (duration < 10 * 60 * 1000) return new Date (lastTried + 60 * 1000); // 1min else if (duration < 60 * 60 * 1000) return new Date (lastTried + 5 * 60 * 1000); // 5min else if (duration < 12 * 60 * 60 * 1000) return new Date (lastTried + 15 * 60 * 1000); // 15min else return new Date (lastTried + 60 * 60 * 1000); // 1h } /** * @return the sequence */ public synchronized int getSequence () { // default getter (brpocock, Jul 14, 2009) return sequence; } /** * @return The date and time at which this payment was made */ public Date getStamp () { return stamp; } /** * FIXME ... this is silly ... ? COMPARE it? * * @return verify the payment's information against the transaction * gateway */ public synchronized Payment getStatusFromGateway () { return paymentGateway.getPayment (transactionCode); } /** * @return The user enrolment for which this payment was made. */ public UserEnrolment getUserEnrolment () { return userEnrolment; } /** * * @param orderSourceID WRITEME * @param orderCodeString WRITEME * @param paymentSequenceNumber WRITEME * @throws NotFoundException WRITEME */ private void init (final String orderSourceID, final String orderCodeString, final int paymentSequenceNumber) throws NotFoundException { Connection con = null; PreparedStatement st = null; ResultSet rs = null; try { con = AppiusConfig.getDatabaseConnection (); st = con .prepareStatement ("SELECT * FROM payments WHERE order_source=? AND order_code=? AND sequence=?"); st.setString (1, orderSourceID); st.setString (2, orderCodeString); st.setInt (3, paymentSequenceNumber); if (st.execute ()) { rs = st.getResultSet (); rs.next (); this.set (rs); } } catch (final SQLException e) { throw new NotFoundException (orderSourceID + "-" + orderCodeString + "." + paymentSequenceNumber); } finally { if (null != rs) { try { rs.close (); } catch (final SQLException e) { /* No Op */ } } if (null != st) { try { st.close (); } catch (final SQLException e) { /* No Op */ } } if (null != con) { try { con.close (); } catch (final SQLException e) { /* No Op */ } } } } /** * @return true if the payment is closed. See {@link #closed} */ public boolean isClosed () { return closed; } /** * @return true if the payment has been completed (successfully or * otherwise) */ public boolean isCompleted () { return stamp == null ? false : true; } /** * @return true if the payment was successful. */ public synchronized boolean isSuccess () { return success; } /** * @return true, if this was a test (and not an actual payment) */ public boolean isTest () { return testMode; } /** * @return the verified */ public boolean isVerified () { return verified; } /** * If a payment should retry processing in future (e.g. failure of * payment gateway) this is where we enqueue that attempt * * @param retryPaymentException the exception causing this to be * scheduled for a do-over * @throws DataException ... * @throws AlreadyUsedException ... */ public void prepareForRetry ( final RetryPaymentException retryPaymentException) throws AlreadyUsedException, DataException { if (firstTried == null) { firstTried = new Date (System.currentTimeMillis ()); } throw AppiusClaudiusCaecus.fatalBug (new RuntimeException ( "Unimplemented")); // FIXME: Schedule event using PDS // AppiusClaudiusCaecus.scheduleEvent (this.getRetryTime (), // this, // "retry"); } /** * @see org.starhope.appius.sql.SQLPeerDatum#set(java.sql.ResultSet) */ @Override protected synchronized void set (final ResultSet rs) { try { order_source = rs.getString ("order_source"); order_code = rs.getString ("order_code"); setSequence (rs.getInt ("sequence")); setPrice (rs.getBigDecimal ("price")); setPaid (rs.getBigDecimal ("paid")); transactionCode = rs.getBigDecimal ("transaction_id"); payer = rs.getString ("payer"); stamp = rs.getTimestamp ("stamp"); } catch (final SQLException e) { throw AppiusClaudiusCaecus.fatalBug (e); } } /** * @param credentials1 the credentials to set * @throws AlreadyUsedException if the payment is closed */ public void setCredentials (final PaymentCredential credentials1) throws AlreadyUsedException { synchronized (this) { assertOpen (); credentials = credentials1; // no need to set "changed," since credentials are not // persistent. } } /** * @param expiryMonth1 the expiryMonth to set */ public synchronized void setExpiryMonth (final int expiryMonth1) { // default setter (brpocock, Sep 11, 2009) expiryMonth = expiryMonth1; } /** * @param expiryYear1 the expiryYear to set */ public synchronized void setExpiryYear (final int expiryYear1) { // default setter (brpocock, Sep 11, 2009) expiryYear = expiryYear1; } /** * @param transactionCodeNumber the transaction code number returned * by the payment gateway * @throws AlreadyUsedException if this payment has already gotten a * transaction number */ public synchronized void setGatewayTransactionCode ( final BigDecimal transactionCodeNumber) throws AlreadyUsedException { synchronized (this) { if (null != transactionCode) throw new AlreadyUsedException (transactionCode .toPlainString (), stamp); transactionCode = transactionCodeNumber; } } /** * @param paid1 the amount paid */ public void setPaid (final BigDecimal paid1) { paid = paid1; } /** * @param newPayer The payer for this payment */ public synchronized void setPayer (final String newPayer) { payer = newPayer; } /** * use {@link #setPaymentFor(String)} instead. * * @param payment_for1 WRITEME */ @Deprecated public void setPayment_for (final String payment_for1) { setPaymentFor (payment_for1); } /** * @param payment_for1 the payment_for to set */ public void setPaymentFor (final String payment_for1) { paymentFor = payment_for1; } /** * @param paymentGatewayReal Set the payment gateway through which * this payment was made * @throws AlreadyUsedException if the payment has already been made */ public void setPaymentGateway ( final PaymentGatewayReal paymentGatewayReal) throws AlreadyUsedException { synchronized (this) { if (stamp != null) throw new AlreadyUsedException (paymentGateway .toString (), stamp); if (paymentGatewayReal instanceof PaymentGateway) { paymentGateway = paymentGatewayReal; } else { paymentGateway = PaymentGateway .getByClass (paymentGateway.getClass ()); } } } /** * @param price1 the price to set */ public void setPrice (final BigDecimal price1) { // default setter (brpocock, Jul 15, 2009) price = price1; } /** * @param resultReason1 the failedReason to set */ public void setResultReason (final String resultReason1) { resultReason = resultReason1; } /** * @param sequence1 the sequence to set */ public synchronized void setSequence (final int sequence1) { sequence = sequence1; } /** ** Note: Once this routine has been called, most of * the setters in this Payment will refuse to operate. It will begin * closing-out. Only post-transaction setters will work, and they * will stop working once {@link #close()} is called. *
** This also causes the Payment object to * permanently discard the credentials used for payment. *
* * @param success1 true if the payment succeeded, false otherwise. */ public synchronized void setSuccess (final boolean success1) { success = success1; // Sequential payments do not store credentials if (null != credentials) { expiryMonth = credentials.getExpiryMonth (); expiryYear = credentials.getExpiryYear (); } stamp (); } /** * @param testMode1 If true, then this is meant to be a test * transaction, and not a real payment. * @throws AlreadyUsedException if this payment has progressed too * far to be marked as a test now */ public void setTest (final boolean testMode1) throws AlreadyUsedException { if (null != stamp) { synchronized (stamp) { if (closed == false) { testMode = testMode1; } else throw new AlreadyUsedException ( "Payment committed", stamp); } } } /** * @param verified1 the verified to set */ public void setVerified (final boolean verified1) { verified = verified1; } /** * @return true, if the engine should retry this transaction */ public boolean shouldRetry () { try { if (getRetryTime ().before ( new Date (System.currentTimeMillis ()))) return true; } catch (final AlreadyUsedException e) { return false; } catch (final DataException e) { return false; } return false; } /** * Destroy the credentials utterly, once and for all. */ public void shredCredentials () { if (null != credentials) { credentials.shred (); } credentials = null; if (null != price && null != stamp) { flush (); } else if (null == price) { AppiusClaudiusCaecus .reportBug ("Not flushing payment because price is not set."); } else if (null == stamp) { AppiusClaudiusCaecus .reportBug ("Not flushing payment because payment is not stamped."); } } /** * * TODO: document this method (brpocock, Oct 13, 2009) * */ public void stamp () { stamp = new Timestamp (System.currentTimeMillis ()); } /** ** Note, we do not save credentials to any kind of stream * or storage (JSON, SQL, &c.). Likewise, firstTried is useless in * future, since it's only useful in concert with credentials for * orders that need a retry. *
* * @see SQLPeerDatum#toJSON() * */ @Override public JSONObject toJSON () { final JSONObject o = new JSONObject (); try { o.put ("FIXME", "FIXME"); o.put ("stamp", JSONUtil.toJSON (getStamp ())); } catch (final JSONException e) { AppiusClaudiusCaecus.reportBug (e); throw new Error (e); } return o; } /** * */ @Override public String toString () { return String.format ("Payment %4s-%30s-%03d", order_source, order_code, sequence); } }