Falcon Payments Providers

Each payment provider should have its own package. We created some simple interfaces to make integration easy!

Payment Provider Interface

Every provider that runs through Falcon Payments requires the following methods:

export interface ProviderInterface {

getAppliedSurcharge(method: string, inquiry: PaymentMethodSurchargeInquiry): null | Surcharge;

getMethodList(payload: PaymentLoadPayload): Promise<PaymentMethodList>;

loadMethod(method: string, payload: PaymentLoadPayload): Promise<PaymentMethodInstance>;

validate(payload: PaymentValidationPayload, method?: string): Promise<PaymentValidationResult>;

}

Get surcharges

getAppliedSurcharge

This method gets any surcharges applied for the payment method. To learn more about surcharges please see our features documentation.

Parameters

• method (string) - payment method code (e.g. paypal or creditcard)
• inquiry (PaymentMethodSurchargeInquiry) - { country: string; currency: string; total: number; }

Returns

This method returns null or Surcharge

type Surcharge = {

/** Total amount of the surcharge */

amount: number;

/** Fixed amount of the surcharge */

fixed?: number;

/** Percentage value of the surcharge */

percentage?: number;

};

Get methods

getMethodList

This method gets the list of available payment methods from a provider.

Parameters

• payload (PaymentLoadPayload)

type PaymentLoadPayload = {

/** Order/cart ID */

id: string;

/** Cart grand total (excluding the payment surcharge) */

total: number;

/** Order currency */

currency: string;

/** Order Billing email */

email: string;

/** Billing country code used for billing, in [ISO_3166-1_alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) format */

country: string;

/** Customer ID to be attached to the Payment Transaction */

customerId?: string;

/** Extra configuration data related to the payment method */

data?: object;

};

Returns

This method returns an array of payment methods (PaymentMethodList)

type PaymentMethodList = Array<PaymentMethodInstance>;

type PaymentMethodInstance = {

/**

* The name of the payment service provider

*/

provider: string;

/**

* A sub method identifier of the payment service

*/

method: string;

/**

* Additional configuration

*/

config?: { [key: string]: any };

/**

* A surcharge for this payment method for the specified country and currency

*/

surcharge?: Surcharge;

};

Load method

loadMethod

Load method is used to pass additional data from the payment provider to the client. Often this is authentication to allow the client to load some form of UI.

Parameters

• method (string)
• payload (PaymentLoadPayload)

Returns

• PaymentMethodInstance

type PaymentMethodInstance = {

/**

* The name of the payment service provider

*/

provider: string;

/**

* A sub method identifier of the payment service

*/

method: string;

/**

* Additional configuration

*/

config?: { [key: string]: any };

/**

* A surcharge for this payment method for the specified country and currency

*/

surcharge?: Surcharge;

};

Validate Payment

validate

The validate method is called when the customer places an order (usually in the final step of a checkout). This method passes the order data to the payment provider and returns information about the status, possibly including data to finish the payment at the front-end.

Parameters

• method (string)
• payload (PaymentValidationPayload)

type PaymentValidationPayload<T = object> = {

/** The user's billing address */

billingAddress: PaymentAddress;

/** The user's shipment address */

shippingAddress: PaymentAddress;

/** The user's locale */

locale: string;

/** The total payment amount */

total: TotalSummary;

/** Cart (product) items */

items: PaymentProduct[];

/** An optional order reference number, will be equivalent to id if left out */

orderReference?: string;

/** Additional payment data - usually for data that is specific to that provider */

data?: T;

} & Pick<PaymentLoadPayload, 'id' | 'customerId' | 'currency' | 'email'>;

Returns

This method returns PaymentValidationResult. It has an optional parameter intermediateStep, this indicates if another step is needed (e.g. redirect to another page or make another request).

type PaymentValidationResult = {

/**

* [optional] External ID of the transaction to be stored on the shop backend

*/

id?: string;

/**

* An additional step to be performed at the frontend

*/

intermediateStep?: {

/**

* Issuer URL (target URL) for redirection

*/

url: string;

/**

* HTTP method (GET or POST, get represents user redirect,

* post represents sending data on the user's behalf)

*/

method: 'GET' | 'POST';

/**

* The fields to send

*/

fields?: { name: string; value?: string }[];

};

};