If you're looking to build a module or template for BigTree that deals with taking payments but either don't want to deal with the APIs directly yourself or want to make your system flexible for re-use with other clients on a different gateway, BigTreePaymentGateway is the class to use.
The Payment Gateway class allows you to use a set of common methods no matter what payment gateway is setup in Developer: authorize, capture, cardType, charge, createRecurringPayment, refund, and void. When calling any method in the class, errors and other messages will be stored in the "Method" property of your class instance.
Supported services: PayPal Payments Pro, PayPal PayFlow Gateway, PayPal REST API, Authorize.Net, and First Data / LinkPoint.
Gateway Agnostic Calls
authorize
This method allows you to authorize a charge to a user's card. This places a hold on the card but doesn't actually take money from it. It's meant to be used in tandem with the capture method and returns the authorization id needed for it if the authorization is sucessful. The "Last4CC" property in your class instance is set with the last 4 digits of the user's credit card number. This is often required for the refund method.
capture
This method allows you to pass in an authorization id from the authorize method in order to actually take money from the authorized card. Returns a transaction id if successful.
cardType
This method allows you to pass in a user's card number and receive the name of the card type (i.e. "visa" or "discover"). This is useful for helping a user confirm their number is valid through highlighting the type of card in your user interface. In some APIs, it's required that you pass in the type of card so this method is also used internally.
charge
This method is equivalent to calling both authorize and capture. Returns a transaction id if successful. The "Last4CC" property in your class instance is set with the last 4 digits of the user's credit card number. This is often required for the refund method.
createRecurringPayment
If your payment gateway is setup to support it (in many, this is an optional feature that is an additional charge) this method will create a recurring payment and return a subscription id if successful.
refund
This method refunds a previously captured transaction. If there is only an authorization, you will want to use the void method. The refund method accepts a transaction id (not an authorization id) and in many cases requries the last 4 digits of the credit card number used for the transaction (so it's a good idea to store them somewhere for later refunds).
void
This method voids an authorization that has not yet been captured. It will remove the hold from a user's credit card.
PayPal Specific Calls
PayPal supports "Express Checkout" through it's three APIs: Payments Pro, Payflow Gateway, REST API. This allows you to setup a checkout system that allows the user to login through PayPal instead of entering their credit card information. The terms of use for most PayPal APIs require you to provide this method for users, so it's good to keep in mind.
In general, the process for this is:
- Call paypalExpressCheckoutRedirect with the amount you wish to charge the user (this can be changed later) along with the URLs for where the user should end up on success and cancellation of the checkout process.
- On the success URL you should have a token entry in your $_GET variable. You can use this token to call paypalExpressCheckoutDetails to find out more information about the user (shipping address, for example).
- You can call paypalExpressCheckoutProcess to actually capture the funds from the user's PayPal account. You must pass in the Payer ID and Token that PayPal returns (normally in the $_GET variable on the return page). You can also pass in a final total to charge the user if it is different from the original amount.
PayPal REST API also provides the ability to store credit cards in their "Vault". This allows you to store a user's credit cards on your website without actually storing their credit card numbers. You can browse the paypalRESTVault* methods on the Payment Gateway Class Reference.