Payment Methods

Payment methods rendering

When a session is configured, it is possible to request a list of available payment methods. These methods come from the configured terminals of Merchant's gateway on altapaysecure.com which the user has access to. Session configuration and customer data is used to determine which payment methods are available. You can either:

delegate rendering of payment methods to IAltaPay session object on your frontend or
retrieve them on the backend and render them on your frontend using your own frontend code.

JS SDKREST API

In order to render payment methods on Merchant's frontend side, you need to use injectPaymentMethods method of IAltaPay session object. This method accepts an HTML element as a parameter, where payment methods will be rendered.

paymentSession.injectPaymentMethods(document.getElementById('payment-methods-list'));

injectPaymentMethods is returning Promise<IAltaPay> which is resolved when payment methods are rendered. This will help you react to the payment methods rendering process - for example, you can show a loading spinner while payment methods are being rendered or react in case of any errors.

paymentSession.injectPaymentMethods(document.getElementById('payment-methods-list'))
.then((altapay) => {
    // any actions you want to perform after payment methods are rendered
    console.log('Payment methods rendered correctly');
    closeLoadingSpinner();
})
.catch(error => {
    // any actions you want to perform in case of error
    console.log("Payment methods rendering failed")
    handleError(error);
});

All errors thrown during payment methods rendering process are triggering JS failure callback if set.

In case there are no payment methods available, injectPaymentMethods will return rejected promise and call JS failure callback if set. This might happen due to misconfiguration on the backend side or due to configuring session in such way that no payment methods are available for the given order.

Remember

Please fill in all the required information while configuring checkout session such as order and customer data.

In order to render payment methods on Merchant's backend side, you need to make a GET request on /checkout/v1/api/payment-methods endpoint with JWT token in the header.

curl --location --request GET 'https://{checkout-api-url}.altapaysecure.com/checkout/v1/api/session/{sessionId}/payment-methods'

Response will contain a list of available payment methods, which you can render on your frontend.

[
    {
        "id": "AltaPay Checkout CreditCard Terminal",
        "type": "CARD",
        "description": "AltaPay Checkout CreditCard Terminal",
        "logoUrl": "https://{checkout-api-url}.altapaysecure.com/checkout/static/methods/logos/credit-card-logo.png",
        "display": "LIST",
        "onInitiatePayment": {
            "type": "URL",
            "value": "https://{checkout-api-url}.altapaysecure.com/checkout/v1/api/payment"
        },
        "gatewayMethodIdentifier": "1e5c1b5e-1b5e-1b5e-1b5e-1b5e1b5e1b5e",
        "metadata": {
            "canIssueNewCredit": "false",
            "canUseCredit": "true",
            "configuration.paymentType": "PAYMENT",
            "shopName": "AltaPay Checkout Shop",
            "terminalName": "AltaPay Checkout CreditCard Terminal"
        }
    },
    { ... }
]

Please refer to the GET /checkout/v1/api/session/{sessionId}/payment-methods endpoint OpenAPI specification for more details.

Default HTML payment method layout

Default HTML components, generated for available payment methods, looks like this:

<div id="payment-methods-list" style="display: inline-grid;">
    <h3>Place where Checkout API will insert payment methods</h3>
    <div class="payment-method-element" id="AltaPay Checkout CreditCard Terminal">
        <div id="AltaPay Checkout CreditCard Terminal" class="logo" style="float: left; vertical-align: middle; opacity: 0.5;">
            <img src="https://{checkout-api-url}.altapaysecure.com/checkout/static/methods/logos/credit-card-logo.png" width="30px" height="30px">
        </div>
        <div style="float: left; vertical-align: middle;">
            <p>CreditCard</p>
        </div>
    </div>
    <div class="payment-method-element" id="AltaPay Checkout MobilePay Test Terminal DENMARK">
        <div id="AltaPay Checkout MobilePay Test Terminal DENMARK" class="logo" style="float: left; vertical-align: middle; opacity: 0.5;">
            <img src="https://{checkout-api-url}.altapaysecure.com/checkout/static/methods/logos/mobile-pay-logo-small.png" width="30px" height="30px">
        </div>
        <div style="float: left; vertical-align: middle;">
            <p>MobilePay</p>
        </div>
    </div>
</div>

Payment method filtering

Available payment methods are calculated based on the following criteria:

Currency

We verify if the payment method supports the currency of the given order. It is based on the Merchants' setup within AltaPay - A MarketPay Company.

Country

We verify if the payment method is restricted to specific countries. It is based on the Merchants' setup within AltaPay - A MarketPay Company. In this step we are comparing billing address of the customer with the list of countries supported by the payment method.

Payment methods ordering

By default, payment methods are displayed in the order of their creation during Merchant's setup with AltaPay - A MarketPay Company.

For legal requirements in some countries, additional order may be applied:

Finland - for more details, please see: Finnish Consumer Protection Act 38/1978
Sweden - for more details, please see: Swedish Payment Services Act (2010:751)

Payment method customisation

Payment method metadata

metadata section contains 'paymentType' mandatory field with following possible values: PAYMENT, AGREEMENT. It indicates which type of payment will be used if the given payment method is chosen. It is important that merchant displays to customer 'Terms and conditions' if the 'paymentType' = AGREEMENT.

Besides that, if you wish to customise appearance, visibility or ordering of the payment methods presented to your customers based on the payment method itself, you can use metadata section containing extra information about the payment method.

Currently available metadata fields:

Field name	Type	Presence	Description
paymentType	string	always	Indicates which type of payment will be used if the given payment method is chosen.
terminalName	string	always	The name of the terminal used to process the payment.
canUseCredit	boolean	always	Can this payment method involve using credit or other deferred payment methods.
canIssueNewCredit	boolean	always	Can this payment method involve applying for new credit agreement.
product	string	optional	Name of the product line if given payment method is known under different business brands.

Customisation guidelines

Please select approach you want to use to learn more about available options:

JS SDKREST API

Altapay SDK offers the possibility to customize the payment methods rendering using the render Payment Method callback functionality.

You should call onRenderPaymentMethodCallback method of IAltaPay session object before calling injectPaymentMethods, and pass the callback function that AltaPay - A MarketPay Company will call for every Payment Method that will be rendered.

The the callback function passed on the onRenderPaymentMethodCallback should have the following signature: function(onRenderPaymentMethodEvent) => HTMLElement. Please check JS SDK Documentation form more details.

paymentSession.onRenderPaymentMethodCallback(function (onRenderPaymentMethodEvent) {
    // the handler function you send as parameter will called automatically for every Payment Method which will be rendered
    return htmlElement;
});

And here with more complete example:

const paymentSession = Altapay.init(token);
// more paymentSession configuration code here 

// custom rendering callback
paymentSession.onRenderPaymentMethodCallback(function (onRenderPaymentMethodEvent) {
// the handler function you send as parameter will called automatically for every Payment Method which will be rendered
return htmlElement;
});

// injecting payment methods into the website
paymentSession.injectPaymentMethods(document.getElementById('payment-methods-list'));

There are some scenarios base on which you can customize the payment method rendering:

Filter out the payment method

In case you want to not allow payments with a specific payment method, you can filter it out based on your own rules. In order to filter out one payment method, the handler function you provided in onRenderPaymentMethodCallback should return null.

paymentSession.onRenderPaymentMethodCallback(function (onRenderPaymentMethodEvent) {
    // use the details that onRenderPaymentMethodEvent provides to decide to filter out the payment method
    if(//should filter out) {
        return null;
    }
    return paymentMethodElement;
});

You can filter out only the remaining payment methods after the default filtering done by AltaPay - A MarketPay Company based on the context.

Customize the design of the AltaPay payment method element

If you want, you can only apply your own style to the payment method element AltaPay - A MarketPay Company provides by default. In order to do it, in the handler function you provided in onRenderPaymentMethodCallback you should apply the desired style on the defaultPaymentMethodElement from onRenderPaymentMethodEvent and return it in the response of the onRenderPaymentMethodCallback handler function. See the default Payment Method layout here.

paymentSession.onRenderPaymentMethodCallback(function (onRenderPaymentMethodEvent) {
    // design the defaultPaymentMethodElement from onRenderPaymentMethodEvent
    onRenderPaymentMethodEvent.defaultPaymentMethodElement.style.verticalAlign = 'middle';
    return onRenderPaymentMethodEvent.defaultPaymentMethodElement;
});

Provide your own payment method element

Render Payment Method callback functionality allows you to provide your own payment method element. In order to do it, you should return in the response of the onRenderPaymentMethodCallback handler function, your own html.

paymentSession.onRenderPaymentMethodCallback(function (onRenderPaymentMethodEvent) {
    // use the details from onRenderPaymentMethodEvent to design your html element
    // this is just a mock example
    let paymentMethodElement = document.createElement('div');
    paymentMethodElement.id = onRenderPaymentMethodEvent.paymentMethod.id;

    let paymentMethodLogoElement = document.createElement('div');
    paymentMethodLogoElement.innerHTML = "<img alt=\""+  onRenderPaymentMethodEvent.paymentMethod.description +"\" src=\"" +  onRenderPaymentMethodEvent.paymentMethod.logoUrl + "\" width=\"30px\" height=\"30px\">";

    paymentMethodElement.appendChild(paymentMethodLogoElement);
    paymentMethodElement.onclick = function (ev) {
        const clickedPaymentMethodElement = ev.currentTarget;
        onRenderPaymentMethodEvent.onSelectPaymentMethodCallback();
        // add also other custom behavior
    };

    return paymentMethodElement;
});

Please attach the onRenderPaymentMethodEvent.onSelectPaymentMethodCallback to the custom html element you provide.

You need to render payment methods on your side based on the data from GET request on /checkout/v1/api/payment-methods endpoint. You can use metadata section for extra information.

Finnish Consumer Protection Act 38/1978

Please be aware of an amendment of the Finnish consumer credit legislation (Finnish Consumer Protection Act 38/1978, as amended) which is effective from October 1st, 2023.

The new amendment means that the order, in which the available payment methods can be presented to consumers in e-commerce, will be subject to strict regulation:

Consumers must first be presented with 1) non-credit-based payment methods that do not include the possibility to apply for or use credit or other deferred payment methods. These include, for example, direct bank transfer or debit cards.
Secondarily, consumers may be presented with 2) payment methods that may include the possibility to apply for or use credit or other deferred payment methods. These include credit cards or payment applications such as MobilePay, which the consumer could also choose to link to a credit card.
Lastly, the consumer may be presented with 3) payment methods that involve applying for or using credit or other deferred payment methods, including entering into a credit agreement.

In addition, no payment method may be used as the default choice at checkout if more than one payment method is available.

Altapay's Checkout solution is compliant with the new legislation out-of-the box providing a contextual ordering of the payment methods.

Swedish Payment Services Act (2010:751)

The new provision applies in the situation where a consumer buys goods or services online, and contains two new requirements:

If an online merchant offers at least one payment method that doesn't require extending credit to the consumer, that particular method must be displayed first. This could be in the form of a list showcasing the available payment options. It's important to note that this amendment doesn't mandate online merchants to accept a credit-free payment method; they are still free to choose which payment methods they prefer to accept.
If an online merchant offers at least one payment method that doesn't require credit, the options involving credit must not be automatically chosen or pre-selected on the merchant's website or mobile shopping app.

This amendment entered into force on 1 July 2020.

Altapay's Checkout solution is compliant with the new legislation out-of-the box providing a contextual ordering of the payment methods.