Anatomy of payment systems in Drupal 8

Oleg Natalushko http://drupal.org/u/niko

Plan

• Current status of payments in Drupal 8.• Common developers mistakes.• Drupal commerce 2.x payment• Payment• Payment offsite API

About me

• More than 100 implemented drupal projects.• 15 years experience Backend developer • 5 years experience Drupal developer• Maintainer of commerce interkassa• Maintainer of Payment platon• Maintainer of commerce probokassa• Maintainer of Payment offsite API

Payment types.

• Payment emulation• On site• Off site

Drupal payment contrib.

Drupal 7• Drupal commerce 1.x• Payment• Payment Gateway API

Drupal 8• Drupal Commerce 2.x • Payment• Payment offsite API

W3C PAYMENT REQUEST API SPECIFICATION• Payment Request API • Basic Card Payment

• Payment Method Identifiers

https://www.w3.org/TR/payment-request/

Payment workflow

Real payment workflow

Real payment workflow (Drupal developer think)

Checkout Payment system IPN call* Result page

Known contrib issues

• Partitional payment not supported• Support only one payment instance per payment module • Not fixed result pages

• Success URL: checkout/ORDER_ID/payment/return/ORDER_PAYMENT_REDIRECT_KEY

• Fail URL: checkout/ORDER_ID/payment/back/ORDER_PAYMENT_REDIRECT_KEY

• Payment transaction created only on success• Send order ID to payment system• Custom result urls used

Drupal commerce 2.x plan

- The payment gateway config entity + UI- The payment gateway plugin type- The payment type YAML plugin- The credit_card payment type- The payment method content entity (for storing tokenized payment information), which uses the payment types as bundles- The payment content entity, which uses payment types as bundlesA payment would have a workflow:New -> Pending -> Complete -> Cancelled | (Partially) Refunded.https://www.drupal.org/node/2711013

Payment method configuration

Payment method configuration

Payment module

•Config, Schema and Plugin•Implement PaymentMethodConfigurationBase

• processBuildConfigurationForm() including tabs magic

• defaultConfiguration()• buildConfigurationForm()• validateConfigurationForm()• submitConfigurationForm()• Status Selector (5 methods)

Payment Offsite API module

•Config, Schema, Plugin•Implement PaymentMethodConfigurationBaseOffsite

• processBuildConfigurationForm()• validateConfigurationForm()• submitConfigurationForm()• defaultConfiguration()

Payment form

Payment form

Payment module requirements

•Implement Routing•Implement Redirect form controller (with cleanup)•Implement Access controller•Implement signature generator•Implement is configured checker•Auto submit library

• Implement Operation provider (configuration loader) getPaymentMethodConfiguration()

• Implement payment method deriver getDerivativeDefinitions()

Payment Offsite API module

PaymentMethod plugin•Extend PaymentMethodBaseOffsite or PaymentMethodOffsiteSimple•Implement

• paymentForm()• isConfigured()• getSignature() (simple)

•Use $this->addPaymentFormData()•Use $this->generateForm()•Configure auto submit via UI

Payment result pages

Payment system

IPN callback

Call Result pages callback

Success page

Pending page

Fail pageHidden fallback call (optional)

Payment result pages

Payment module requirements

•Implement • Routing• Result pages controller• Access controller

•Fallback support (optional)

Payment Offsite API module

PaymentMethod plugin•Implement

• getResultPages()• get<Result>Content()• getSignature() (simple)

•Fallback call supports per result page using getResultPages()

Payment IPN callback

Payment system

IPN callback Call IPN Access check

Call IPN Validate

Call IPN Execute

Set order internal status according to

status mapping

Payment method plugin + configuration

Payment IPN callback

Payment module require

Implement•Routing•IPN controller•IPN validator•Access controller

Payment Offsite API module

Implement in PaymentMethod plugin•ipnExecute()•ipnValidate()

Also you could extend PaymentMethodOffsiteSimple and use•validateEmpty()•validateRequiredKeys()•validateMerchant()•validateSignature()•validateTransactionId()•validateAmount()

You must implement if going to use default validators:•getMerchantIdName()•getTransactionIdName()•getAmountName()•getSignatureName()•getRequiredKeys()

Payment offsite API Interface

interface PaymentMethodOffsiteInterface { public function ipnExecute(); public function ipnValidate(); public function getResultPages(); public function paymentForm(); public function isConfigured();}

Payment offsite API Simple Interfaceinterface PaymentMethodOffsiteSimpleInterface extends PaymentMethodOffsiteInterface {

const SIGN_IN = 'IN'; const SIGN_OUT = 'OUT'; public function getSignature($signature_type = self::SIGN_IN); public function getMerchantIdName(); public function getTransactionIdName(); public function getAmountName(); public function getSignatureName(); public function getRequiredKeys();

}

Payment offsite API

• Fully compatible with Payment module• Fallback mode support• Multiple payment instances support • Simplify payment method creation• IPN and result pages callbacks• Payment form

@Todo provide integration to commerce_payment@see https://www.drupal.org/sandbox/niko/2685859

Thank you

Oleg Natalushko Site: http://bighameleon.comSkype: onatalushkoPhone: +380674176171Drupal.org: https://www.drupal.org/u/niko