Integration Guide

Introduction

This guide outlines how to integrate with a custom payment provider using the Fonteva Services platform. It goes into detail on where the different calls are executed to ensure that when a custom provider is used, the end user experience is not affected. All features outlined in this guide require 2019-R1 or later of the FDService (Fonteva Services).

Lightning Component For Custom Payment Type

A Lightning Component is required when using a non-Spreedly enabled payment provider. The Lightning Component needs to extend an interface OrderApi:CustomPaymentTypeInterface which allows the platform to instantiate the component and show it on the checkout page. Sample code is:

<aura:component description="StripeOffsitePayment" implements="OrderApi:CustomPaymentTypeInterface" access="global" controller="ProcessStripePayment">
    <ltng:require scripts="{!join(',',$Resource.Framework__UrlUtil,$Resource.Framework__ActionUtils)}"/>
    <aura:attribute name="creditCardObj" type="Map" default="{}"/>
    <aura:registerEvent name="ButtonToggleIndicatorEvent" type="Framework:ButtonToggleIndicatorEvent"/>
    <aura:registerEvent name="StopIndicatorEvent" type="OrderApi:StopIndicatorEvent"/>

    <div class="slds-col slds-grid">
        <div class="slds-size--1-of-1 slds-m-bottom-x--small slds-text-align_center" data-name="fullNameWrapper" aura:id="fullNameWrapper">
            <Framework:Button imageSrc="https://t.alipayobjects.com/images/T1HHFgXXVeXXXXXXXX.png" onClickAction="{!c.processPayment}" qaData='{"type" : "button", "name": "processBtn"}' aura:id="processBtn" group="paymentButtons" label="" type="neutral"/>
        </div>
    </div>
</aura:component>

Please refer to the Custom Payment Type Documentation on how to configure.

Actions To Override

There are actions that in the payment service that must be overridden to have a full experience. Each action listed below is executed through the customer payment lifecycle. To override these actions, please read the following guide. A global override will need to be used because some of the actions listed below are executed in a trigger or batch context.

Purchase

This call is executed after the payment method is already tokenized and the credit card needs to be charged. This method is called both by the UI and by the Scheduled Payment batch job. The following code needs to be provided in the overriding class:

    public override FDService.EPayResponse purchase(FDService.EPayRequest request) {
        String payload = 'source='+request.paymentMethod.paymentMethodToken+'&amount='+request.amount+'&currency='+request.currencyISOCode+'&description="'+request.orderId+'"';
        HttpResponse resp  = StripeHTTPExecutor.executeRequest('POST','/charges',payload);
        return mapResponse(resp);
    }

From the above example, you can see that the EPayRequest object is being used to generate the callout to the payment provider. As this is not core Fonteva functionality, a custom mapper will need to be built to map the response from the provider back to the Fonteva EPayResponse object. Once this object is hydrated and returned, the system will automatically generate all corresponding records, such as ePayments, Receipts, and Receipt Lines. If the requirement needs the ability to use Spreedly and other gateways in the same environment, then the developer will need to query the Payment Gateway so that the correct execution path is taken.

This call is also used as is for the Scheduled Payment batch job, so the developer only needs to override it once.

Credit

The Credit call is used to refund a transaction using the Receipt object. There is a button on the Receipt to Create Refund and Process Refund. When the Process Refund is executed, the PaymentService.credit method is called. As this method executes in the context of a trigger, the developer will need to perform a global override as stated above.

    public override FDService.EPayResponse credit(FDService.EPayRequest request ) {
        String payload = 'charge='+request.transactionToken;
        HttpResponse resp  = StripeHTTPExecutor.executeRequest('POST','/refunds',payload);
        return mapResponse(resp);
    }

From the above example, you can see that the EPayRequest object is being used to extract the information on what needs to be refunded. If a non-Spreedly gateway is used, the developer will need to write the method to parse the provider response to the EPayResponse object. Once that is returned, the system will auto mark all of the fields and update the Receipt accordingly. If the requirement needs the ability to use Spreedly and other gateways in the same environment, the developer will need to query the Payment Gateway so that the correct execution path is taken.

Verify

If the payment provider requires that the card be verified after the tokenization has occurred to save it for future use, the platform will call PaymentService.verify. This method can be done via contextual override as this action would need to occur before the payment call is executed.

    public override FDService.EPayResponse verify(FDService.EPayRequest request ) {
        String payload = 'token'+request.transactionToken;
        HttpResponse resp  = StripeHTTPExecutor.executeRequest('POST','verify',payload);
        return mapResponse(resp);
    }

From the above example, you can see that the EPayRequest object is being used to extract the information to send to verify the card. Once the card is verified, an OrderApi__Payment_Method__c can be created. This token now can be sent to the purchase call.