HostFact - Payment Provider
Beginnen met ontwikkelen
We zullen u op deze pagina stap voor stap door het ontwikkelproces heen begeleiden.
Aanmaken van een nieuwe map en een payment bestand
In de map 'klantenpaneel/betalen/' dient u een nieuwe map aan te maken met de naam van de payment provider. De map mag geen spaties of bevatten. In deze map plaatst u het voorbeeld bestand 'payment_provider.php' (klik om te downloaden).
Open hierna het bestand 'payment_provider.php' en pas hierin de class-naam aan. Deze naam moet overeenkomen met de naam van de map, waarbij met de volgende voorwaarden rekening gehouden moet worden.
- punten in de map-naam moeten omgezet worden naar underscores.
- een cijfer als eerste karakter in de mapnaam, moet worden omgezet naar het Engelstalige woord voor dit cijfer, gevolgd door een underscore. Dus "2checkout" wordt "two_checkout".
We zullen nu in een logische volgorde de functies behandelen welke geimplementeerd moeten worden.
getBackofficeSettings()
Deze functie zorgt ervoor dat een HostFact gebruiker uw betaalmethode kan toevoegen en configureren. De namen van de instellingen van de betaalmethode zijn aan te passen en standaard waardes kunnen worden meegegeven.
Voorbeeld integratie
public static function getBackofficeSettings() { $settings = array(); $settings['InternalName'] = 'Your Payment Provider'; $settings['MerchantID']['Title'] = "User ID"; $settings['MerchantID']['Value'] = ""; $settings['Password']['Title'] = "Password"; $settings['Password']['Value'] = ""; $settings['Advanced']['Title'] = "Pay by Your Payment Provider"; $settings['Advanced']['Image'] = "yourpaymentprovider.jpg"; $settings['Advanced']['Extra'] = "Please select your payment method:"; $settings['Hint'] = "First create an active profile for your website."; return $settings; }
Key | Beschrijving |
---|---|
InternalName | Naam van de payment provider, welke in HostFact als betaalmethode wordt weergegeven |
MerchantID.Title | Naam voor de instelling: gebruikersnaam |
MerchantID.Value | Standaard waarde voor deze instelling |
Password.Title | Naam voor de instelling: wachtwoord |
Password.Value | Standaard waarde voor deze instelling |
Advanced.Title | Standaard naam van de betaalmethode, zoals getoond aan de betalende klant |
Advanced.Image | Bestandsnaam voor de standaard afbeelding van de betaalmethode. Afbeelding moet in map 'klantenpaneel/betalen/images/' voorkomen |
Advanced.Extra | Standaard titel bij keuze voor betaalmethode/bank in betaalscherm |
Hint | Ruimte voor extra uitleg voor de HostFact gebruiker. Wordt getoond bij het instellen van de betaalmethode |
Indien de MerchantID of Password titles leeg zijn, wordt de instelling niet getoond.
__construct()
Haal de configuratie van de HostFact gebruiker uit HostFact op in de construct-functie van de class. Naast het aangeven van de mapnaam, het type betaalmethode en het laden van de standaard instellingen, kunnen eigen instellingen worden toegevoegd, zoals we in het hoofdstuk over callback URLs zullen zien.
Voorbeeld integratie
function __construct() { $this->conf['PaymentDirectory'] = 'your.classname'; $this->conf['PaymentMethod'] = 'other'; // ideal / paypal / other // Load parent constructor parent::__construct(); // Load configuration $this->loadConf(); }
choosePaymentMethod()
Indien u vooraf een keuze aan de betalende klant wil geven welke betaalmethode of bank gebruikt moet worden, kunt u deze functie implementeren.
Hoeft de klant geen keuze te maken, laat deze functie dan 'false' teruggeven.
Voorbeeld integratie
public function choosePaymentMethod() { // If we don't need to ask for payment method upfront, just return false; return false; // Or get the payment methods and create HTML with options. $html = "<select name=\"my_creditcard\">"; $html .= "<option value=\"\">Please select your creditcard</option>"; $html .= "<option value=\"mastercard\">Mastercard</option>"; $html .= "<option value=\"visa\">Visa</option>"; $html .= "</select>"; return $html; }
validateChosenPaymentMethod()
Indien u vooraf een keuze aan de betalende klant geeft welke betaalmethode of bank gebruikt moet worden, dient u de gekozen betaalmethode te valideren.
Hoeft de klant geen keuze te maken, laat deze functie dan 'true' teruggeven.
Voorbeeld integratie
public function validateChosenPaymentMethod() { // If we don't need to ask for payment method upfront, return true (always valid) return true; // Or check the chosen payment methods and store in session if(isset($_POST['my_creditcard']) && $_POST['my_creditcard']) { $_SESSION['my_creditcard'] = htmlspecialchars($_POST['my_creditcard']); return true; } elseif(!isset($_POST['my_creditcard']) && isset($_SESSION['my_creditcard']) && $_SESSION['my_creditcard']) { return true; } else { $this->Error = 'No creditcard chosen.'; return false; } }
startTransaction()
Zodra de betaling daadwerkelijk gestart moet worden, zal deze functie worden aangeroepen. Indien klantgegevens nodig zijn kunt u de functie $this->getCustomerData() gebruiken. Bij het succesvol starten van de transactie, dient de betalende klant doorgestuurd te worden naar de omgeving van de payment provider.
Beschikbare variabelen | Beschrijving |
---|---|
$this->Type | 'invoice' of 'order', afhankelijk van het object wat betaald wordt |
$this->InvoiceID | ID van de factuur die betaald wordt |
$this->InvoiceCode | Factuurnummer |
$this->OrderID | ID van de bestelling die betaald wordt |
$this->OrderCode | Bestelnummer |
$this->Amount | Te betalen bedrag in notatie: #.## |
Voorbeeld integratie
public function startTransaction() { $chosen_creditcard = (isset($_SESSION['my_creditcard']) && $_SESSION['my_creditcard']) ? $_SESSION['my_creditcard'] : ''; if($this->Type == 'invoice') { $orderID = $this->InvoiceCode; $description = __('description prefix invoice').' '.$this->InvoiceCode; } else { $orderID = $this->OrderCode; $description = __('description prefix order').' '.$this->OrderCode; } $amount = $this->Amount; // Start transaction //TODO: implement here // If transaction can be started if(true) { // If a transaction ID is known, update to database //$this->updateTransactionID($transactionid); // Redirect header("Location: " . $url_to_payment_provider_transaction); exit; } else { // Return error message for consumer $this->paymentStatusUnknown($error_message); exit; } }
validateTransaction($transactionID)
Na de betaling kan de klant vaak doorverwezen worden naar een URL. De verwerking van de status van de factuur of bestelling in HostFact kan op dat moment ook gedaan worden. Naast de terugverwijzing van de klant, kan er ook een directe notificatie van de payment provider naar de server waarop HostFact staat worden gestuurd. Beide aanroepen zullen de validateTransaction methode gebruiken. Belangrijk is dan ook correct onderscheid te maken tussen deze aanroepen, om te voorkomen dat een betaling dubbel verwerkt wordt.
Controleer in deze functie altijd of de aanroep geldig is, door handtekeningen te controleren of de status realtime op te halen bij de payment provider.
Voorbeeld integratie
public function validateTransaction($transactionID) { if($this->isNotificationScript === true) { // Check if payment is succeeded $paid = true; if ($paid === true) { // Update database for successfull transaction $this->paymentProcessed($transactionID); } else { // Update database for failed transaction $this->paymentFailed($transactionID); } } else { // For consumer (in this case the status is already changed by server-to-server notification script) if($this->getType($transactionID) && $this->Paid > 0){ if($this->Type == 'invoice') { $_SESSION['payment']['type'] = 'invoice'; $_SESSION['payment']['id'] = $this->InvoiceID; } elseif($this->Type == 'order') { $_SESSION['payment']['type'] = 'order'; $_SESSION['payment']['id'] = $this->OrderID; } // Because type is found, we know it is paid $_SESSION['payment']['status'] = 'paid'; $_SESSION['payment']['paymentmethod'] = $this->conf['PaymentMethod']; $_SESSION['payment']['transactionid'] = $transactionID; $_SESSION['payment']['date'] = date('Y-m-d H:i:s'); } else { $_SESSION['payment']['status'] = 'failed'; $_SESSION['payment']['paymentmethod'] = $this->conf['PaymentMethod']; $_SESSION['payment']['transactionid'] = $transactionID; $_SESSION['payment']['date'] = date('Y-m-d H:i:s'); } header("Location: ".IDEAL_EMAIL); exit; } }
Bekijk ook het hoofdstuk over Callback URLs voor het ontvangen van terugkoppelingen.