This guide describe payment method creation based on Payment Offsite API

Terminology

  • Instant Payment Notification (IPN) is a message service that automatically notifies merchants of events related to payment transactions.
  • IPN Status is payment transaction status reviced via IPN
  • IPN Callback is special hidden url for IPN comunication with Payment system
  • Merchant is a business person who trades in commodities produced by other people in order to earn a profit.
  • Merchant ID is unique identifier for merchant on payment gateway side
  • Result page is the page on which the user will be redirected after payment

Prerequisites

  1. Create a module.
  2. Analyze payment gateway API to determine settings that you need store on the module side (ex. merchant id, private key ...)
  3. Select IPN statuses, which are required for communication, from the payment gateway API documentation.

Creating configuration plugin

Сonfig scheme

Create a config scheme of the type plugin.plugin_configuration.payment_method_configuration.payment_offsite_api to store these settings.

Configuration plugin

Define the plugin configuration from the prerequisites step 2 and IPN status settings from the prerequisites step 3.

Plugin configuration structure is the following:

Under the key pluginConfiguration you need to define the following required keys:

  • message_text - payment form text
  • message_text_format: payment form text format
  • auto_submit - whether to hold a payment form autosabmit
  • verbose - debug mode
  • ipn_statuses - mapping of statuses from
    step 4 to statuses of the site format <IPN status>: <local status> (list)
  • config - a list of specific payment gateway options with the default values format <parameter>: <value>

Then you should implement configuration plugin extending the PaymentMethodConfigurationBaseOffsite class.

The following methods are required in the configuration plugin:

  • defaultConfiguration() - Default configuration
  • processBuildConfigurationForm() - configuration form
  • validateConfigurationForm() - configuration form validate handler (optional)
  • submitConfigurationForm()- configuration form submit handler
  • getters\setters - (optional).

Creating payment method plugin

Simple payment method plugin

You should implement extending class PaymentMethodOffsiteSimple for the payment method plugin or PaymentMethodOffsiteSimpleInterface interface.
You should use deriver in the payment method annotation - \Drupal\payment_offsite_api\Plugin\Payment\Method\PaymentMethodBaseOffsiteDeriver
and operations_provider - \Drupal\payment_offsite_api\Plugin\Payment\Method\PaymentMethodBaseOffsiteOperationsProvider

You should implement the following interface methods in the payment method plugin:

  • getSignature($signature_type = self::SIGN_IN) - performs signature generation
  • getMerchantIdName() - MerchantId parameter name
  • getTransactionIdName() - payment transaction name on the payment gateway side
  • getAmountName() - payment amount parameter name
  • getSignatureName() - signature parameter name
  • getRequiredKeys() - required parameter list
  • getResultPages() a list of result pages (array with the structure <page name> => <IPN process emulation true/false>) usually
         return [
            'success' => FALSE,
            'fail' => FALSE,
            'pending' => FALSE,
          ];
      

    or

          return [
            'success' => FALSE,
            'fail' => TRUE,
          ];
      
  • Methods getSuccessContent(), getFailContent(), getPandingContent() - generating Result pages for users; you may add any number of such pages (1 per status)
  • paymentForm() - payment form generating method (payment parameters can be added through addPaymentFormData() method)
  • ipnExecute() - IPN request reaction method; payment status change allowed in this method only
  • isConfigured() - method returns true if the payment method has been configured properly.

Extended payment method plugin

If you need to implement a more complex process of communication with payment gateway or your payment gateway has a special communication protocol (for example if merchant id is absent and public key used instead) then you can implement PaymentMethodOffsiteInterface.
In this case, you need to implement the following methods:

  • getResultPages() a list of result pages (an array with the structure <page name> => <IPN validate emulation true/false>)
  • Methods getSuccessContent(), getFailContent()getPandingContent() - generating Result pages for users; you may add any number of such pages (1 per status)
  • paymentForm() - payment form generating method (payment parameters can be added through addPaymentFormData() method)
  • ipnExecute() - IPN request reaction method;payment status change is allowed in this method only
  • ipnValidate() - IPN request validation method; it is recommended to validate the following request parameters: metchant id, signature, order id, amount and currency.
  • isConfigured() - Method should return true if the payment method has been configured properly.

Advanced payment method plugin

You could use this module only to simplify configuration plugin creation and / or use predefined comunication URLs. In this case, you should use the payment module documentation for the development of the payment method

Predefined comunication urls

You need to use the following urls In your payment gateway account:
http://example.com/payment_offsite/{payment_method_configuration}/{external_status}
The following special url has been implemented specifically for IPN
http://example.com/payment_offsite/{payment_method_configuration}/ipn